apidoc: SPHINX_APIDOC_OPTIONS support options not ending with a :

Brief

apidoc forces that the SPHINX_APIDOC_OPTIONS are starting and ending with a :, but there are sphinx options which do not end with a :, which are then unusable.

Problem statement

apidoc supports the SPHINX_APIDOC_OPTIONS environment variable. It is “a comma-separated list of option to append to generated automodule directives”.

Listing 1: They are currently specified as a comma seperated list, for example

members,undoc-members,show-inheritance

Listing 2: apidoc will convert them to a list with preceding and ending :

:members:
:undoc-members:
:show-inheritance:

Listing 3: This is primarily done through the jinja template:
https://github.com/sphinx-doc/sphinx/blob/00efa53decbdf7a49f0883deb61ea5be9e66fb21/sphinx/templates/apidoc/module.rst_t#L7
https://github.com/sphinx-doc/sphinx/blob/00efa53decbdf7a49f0883deb61ea5be9e66fb21/sphinx/templates/apidoc/package.rst_t#L4

That jinja template excludes options which do not end with a :.
Listing 4: For example the following automodule directives could not be expressed with SPHINX_APIDOC_OPTIONS:

:special-members: __and__, __iand__, __or__, __ior__
:exclude-members: __iter__, __call__

So the comma separated list of SPHINX_APIDOC_OPTIONS as in listing 1, limits the available options of sphinx. Especially the commands in listing 4, would be of interest to filter the large amount of auto-generated functions of apidoc.

Proposed Solution

A simple solution could be to change listing 3 to:

{{ option }}

Hence, specify the : in SPHINX_APIDOC_OPTIONS, instead of forcing it in the beginning and end in the jinja template.

As seen in listing 4, , is required as separator in the options, so it cannot be used any more in SPHINX_APIDOC_OPTIONS as an option separator. However, : (space and a colon) would be automatically a valid separator without the need of an additional one.

Therefore, listing 2 and 4 could be expressed in SPHINX_APIDOC_OPTIONS as:

:members: :undoc-members: :show-inheritance: :special-members: __and__, __iand__, __or__, __ior__ :exclude-members: __iter__, __call__

As a consequence the following lines have to be changed in the code (but not more)
https://github.com/sphinx-doc/sphinx/blob/00efa53decbdf7a49f0883deb61ea5be9e66fb21/sphinx/ext/apidoc.py#L36-L45

Caveats

The proposed solution would allow using any option specified in sphinx, but has the main problem that this requires an interface change, e.g. the definition of SPHINX_APIDOC_OPTIONS. However, it cannot be solved without changing SPHINX_APIDOC_OPTIONS in some way or introducing some strange new variable like SPHINX_APIDOC_OPTIONS_COLONS.

We could retain backwards compatibility with a check. If SPHINX_APIDOC_OPTIONS does not contain any colon, it could be parsed the old way, and if there is a colon in the string it is parsed the new way.

Start with sphinx/ext/apidoc.py around the SPHINX_APIDOC_OPTIONS parsing and the apidoc/module.rst_t and package.rst_t templates. Compare the current colon-wrapping behavior with options such as special-members and exclude-members, then determine how the interface change or backward-compatibility behavior should work. Done means generated automodule directives can express options that do not end with a colon without breaking existing values.