The placeholders cause the build to fail:

checking consistency... /home/circleci/project/doc/api/backend_gtk3agg_api.rst: WARNING: document isn't included in any toctree
/home/circleci/project/doc/api/backend_gtk3cairo_api.rst: WARNING: document isn't included in any toctree
/home/circleci/project/doc/api/backend_qt4agg_api.rst: WARNING: document isn't included in any toctree
/home/circleci/project/doc/api/backend_qt4cairo_api.rst: WARNING: document isn't included in any toctree
/home/circleci/project/doc/api/backend_qt5agg_api.rst: WARNING: document isn't included in any toctree
/home/circleci/project/doc/api/backend_qt5cairo_api.rst: WARNING: document isn't included in any toctree
/home/circleci/project/doc/api/backend_tkagg_api.rst: WARNING: document isn't included in any toctree
/home/circleci/project/doc/api/backend_wxagg_api.rst: WARNING: document isn't included in any toctree
done

The placeholders cause the build to fail:

Yep. Those can be orphaned. Looks like the links need to be relative to the directory that they are being made in as well (despite what the docs say). Making them absolute to root probably works too, but doesn't work in the artifacts html...

Well, that works. I'm not a huge fan to be honest, and almost wish we could just have a new sphinx directive. Is that easy? :redirect: ./newpage would be a lot easier than orphaning and adding to the conf.py.

To see how this work, navigate to https://53094-1385122-gh.circle-artifacts.com/0/doc/build/html/api/backend_gtk3agg_api.html and it will take you to
https://53094-1385122-gh.circle-artifacts.com/0/doc/build/html/api/backend_gtk3_api.html

I'll have a look at the directive possibility.

Cool, it should be pretty straightforward. I may look at it as well, but probably a bit of learning curve. For reference, all the reredirects does is change the html to:

<html><head><meta http-equiv="refresh" content="0; url=${to_uri}"></head></html>

It might be nice to spice that up a bit (add a canonical?) but I think even as-is search engines will recognize that this is not supposed to be indexed.

@jklymak See https://github.com/anntzer/sphinx-redirectfrom (quick hack, barely tested, unlikely to eat your dog though). I went for what I think is a slightly nicer approach of not actually requiring to keep the old files in the source tree and having a .. redirect-from:: /path/to/old/src in the new source tree.

Nice, I think I agree thats better, because if we delete the new target, it would be nice to know we have to redirect again. I'll play with that over the w/e. Thanks a lot!

As an example from the build above:
doc/api/backend_qt4agg_api.rst was removed in #19440

In https://github.com/matplotlib/matplotlib/pull/19456/files#diff-46354faebf416277aa00bb8daab45cde2fdbf1318ffdf1e5e1b0a468075798cd we say:

.. redirect-from:: /api/backend_qt4agg_api

So now if you navigate to:

https://53162-1385122-gh.circle-artifacts.com/0/doc/build/html/api/backend_qt4agg_api.html

you are immediately redirected to:

https://53162-1385122-gh.circle-artifacts.com/0/doc/build/html/api/backend_qt_api.html

Namely that moving whole directories will require each file in the directory getting this directive to its new location.

I guess you could support both .. redirect-from:: and a pre-set list of redirects in conf.py for glob redirects (that would just pre-populate the redirects mapping).

Namely that moving whole directories will require each file in the directory getting this directive to its new location.

I guess you could support both .. redirect-from:: and a pre-set list of redirects in conf.py for glob redirects (that would just pre-populate the redirects mapping).

Sure, well we could cross that bridge when we come to it. For now we have a pretty easy way to redirect if we move, so I think this can wait.

jklymak added the status: needs comment/discussion label 4 days ago

In the meeting, or is it okay to merge now?

This is fine from my end. I think folks have had lots of time to voice concerns. Plus its not an irrevocable change if we decide this is a bad way to go.

@timhoffm @story645 @dstansby @brunobeltran This make sense to all of you?

Need to add warning for an overwrite....

.. added a redirect from /users/customizing to /tutorials/introductory/customizing as that was moved in #8545 (as discussed on gitter)

Did we mean to take out examples/subplots_axes_and_figures/subplot_toolbar.py?

Did we mean to take out examples/subplots_axes_and_figures/subplot_toolbar.py?

Ooops! No, I mean we could ;-) It crashes on my machine when I do the doc build.

I think this is still in good shape? I wouldn't mind it being merged so we can start doing more manual redirects