[WIP] Add support for custom section names

[brockdyer03]

Motivated by #202.

WIP Implementation

The implementation I've gotten to work for now is quite rough, but basically can be boiled down to two steps for users. The first is to provide a custom template file, which follows the form of numpydoc_docstring.rst, and just requires that the user add in whichever new section names they want. This template file is then picked up by the variable in conf.py called numpydoc_template_file.

The other part of this is adding in the desired formatting of the new section. This is done through setting numpydoc_extra_sections in conf.py, which is a dictionary with the keys being the section names and the values being the desired format. For example, you could have

numpydoc_extra_sections = {
    "Note": "notes",
    "Members": "member_list",
}

These format values map to the existing string functions in docscrape_sphinx.SphinxDocString, and are matched like so:

"param_list"  : self._str_param_list(section)
"member_list" : self._str_member_list(section)
"returns"     : self._str_returns(section)
"warnings"    : self._str_warnings(section)
"see_also"    : self._str_see_also(section)
"notes"       : self._str_section(section)
"references"  : self._str_references(section)
"examples"    : self._str_examples(section)

To Do

I am not a huge fan of users needing to supply two separate values to get a new section in, however I haven't figured out a way to add in extra sections that I like.

Another thing to do is to update the validation code to recognize custom sections, if that is desired.

Example

I have a minimal example in a branch in my own repository, where all I've done is very simply change Notes to Note in the Element enum.

[stefanv]

We're trying to move away from having a Sphinx dependency, so probably don't want this.

[brockdyer03]

I'd be fine removing it if there's a replacement that has already been agreed on.

[stefanv]

We need to ensure that config is documented somewhere.

[brockdyer03]

I agree. I am not 100% sure what the type of config is everywhere, but I believe it's just a simple dict. I am more sure that it is at least supposed to support the MutableMapping ABC.

[stefanv]

Can probably handle this with set intersections.

[stefanv]

Are these changes related to the PR (looks like they are)? If so, document along with other config options.

[brockdyer03]

Yes. I originally had put the code for the extra templating information there, but realized that it is additionally set in get_doc_object() at the end of that module. I am unsure if it needs to be in both places, but I think it is probably good to have it in both since the one you commented on sets the attributes of SphinxDocString, which already has attributes for the other config options.

[stefanv]

This change doesn't look quite right; ignores the dictionary above?

[brockdyer03]

The dictionary above it is the standard numpydoc sections, which I suppose can be hard-coded for now. After those are set, I iterate over the extra sections that the user provides, and use them to update the above dictionary.

[stefanv]

OK, but do we need to re-handle existing sections in there, or can those be removed and handled via the standard mechanism?

[brockdyer03]

The existing sections aren't touched there. The reason it looks like it is because I am re-using the names of the _str_<section_format>() functions to select the format, which are also the identifiers in numpydoc_docstring.rst.