Use autosectionlabel extension

[stsewd]

I just did a grep to find those links and also to make sure they aren't used in other parts. There are still some links that are used externally (like the yaml file I think) or are out of the scope like the changelog (but I think we can still have those links, going to investigate later).

Closes #4140

[humitos]

I like these changes. I think it's way more clear to know where we are linking to.

I would like to know what happen if we change the title of one of those linked sections. Do we get a lint error? Do we end up with a broken link?

[stsewd]

We end with a none link, the link isn't displayed. I'll see if I can extend rstcheck or use something else. reStructuredText needs a lot of tooling 🔨

[humitos]

OK. I'm interested in making the errors (as changing the title of a section) explicit and communicate them to us. Otherwise, we will end with broken links without knowing it.

[ericholscher]

We could also make the travis-ci docs check run with warnings as errors. I believe we have a few warnings already though, but if we removed all of those, it should catch incorrect references.

[stsewd]

@ericholscher I checked that yesterday, we only have one warning about the _static directory, also I tried activating the -n option, I still don't understand it (I remove some refs and everything still works)

http://www.sphinx-doc.org/en/master/usage/configuration.html#confval-nitpicky

[ericholscher]

Huh, interesting.

[ericholscher]

@stsewd sphinx-doc/sphinx#3919

[ericholscher]

So it looks like our django.setup() in the conf.py is eating the logging output of Sphinx.

[ericholscher]

I actually currently don't see our default Sphinx output in the log for docs locally!

[ericholscher]

Even in prod, it's totally swallowing the Sphinx "each page" logging output:

[ericholscher]

This discussion moved to #4166