add autosectionlabel

[nstarman]

https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html#automatically-label-sections

[pllim]

Is this fully backward compatible?

[nstarman]

My bad. Meant to add this to v2, not v1.

[pllim]

How do you intend to use this over at astropy?

There is no test for this, so we cannot really be sure this new addition will work for all the Sphinx versions the CI claims to support.

[nstarman]

How do you intend to use this over at astropy?

It would be nice not to have to write explicit link targets. In Astropy we seem to have a somewhat analogous, but ad-hoc system. E.g. labelling something .. _astropy_cosmology_io.... This enables Sphinx's "formal" system for link targets, using the file location and section name as the target — .. _astropy/cosmology:io. It looks convenient and sensible structurally.

There is no test for this, so we cannot really be sure this new addition will work for all the Sphinx versions the CI claims to support.

Sphinx Astropy seems not to have a large test suite... https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html claims it should work for Sphinx v1.4+

[pllim]

But this method breaks if you decide to reword the section title, right? Or move pages around?

The explicit way, it does not matter as long as you keep the label there.

[nstarman]

Yes, this method breaks if you change the section title or page arrangement, like how the explicit way breaks if the label is changed. Different things are kept constant: with explicit labels it's the label itself; with implicit labels it's the structural similarity to the topic.

You can still make explicit labels if you want to. This just means you don't have to.

[pllim]

This just means you don't have to.

Sure, but I am also not sure if I should be encouraging astropy to do this... I can see it breaking ref more often this way. People tend to rename titles and move pages, but they very rarely rename a label because the label is not rendered.