DOC: Add headers to docstring sections to add link anchors

[rossbar]

Closes #317.

Converts the docstring sections enumerated in the style guide to subsection headings, which adds link anchors to each section. Also adds internal references in the style guide to the newly-linkable sections.

[larsoner]

Seems to work well:

https://288-11639513-gh.circle-artifacts.com/0/html/format.html#yields

Thanks @rossbar !

[zmoon]

@larsoner it seems like the RTD is not building, due to the default branch name change? Looks like here it still says master.

[jnothman]

Exciting! But we might want to check the effect on things like TOC... Is numpydoc used in contexts where multiple objects are documented in one page? That would also be a case to check in terms of heading hierarchy. But yes, I'm excited to have heading anchors!

[jnothman]

What I'd prefer, I'll admit, is an anchor for each parameter... I wonder if that's possible by processing the tree after parsing

[larsoner]

But we might want to check the effect on things like TOC... Is numpydoc used in contexts where multiple objects are documented in one page?... What I'd prefer, I'll admit, is an anchor for each parameter... I wonder if that's possible by processing the tree after parsing

It sounds like you're talking about having anchors in the docstrings that get processed by NumpyDoc. I thought this, too, when I first read the associated issue and even PR description. But the scope of this is much smaller: it just adds anchors to NumpyDoc's own docs about how to document properly, such as:

https://288-11639513-gh.circle-artifacts.com/0/html/format.html#yields

You can see that the rendered docstring does not have any new anchors:

https://288-11639513-gh.circle-artifacts.com/0/html/example.html

[zmoon]

numpydoc/doc/conf.py

Lines 140 to 142 in b4f2126

	html_sidebars = {
	"**": [],
	}

seems to disable the expansion of the ToC headings. I don't know if this is a bug or a feature but it is unfortunate since it makes the improvement here a bit less useful.

Edit: looks like the fix is to replace it by

html_sidebars = {
    "**": ["sidebar-nav-bs.html"],
}