apidoc: SPHINX_APIDOC_OPTIONS support options not ending with a :

[raabf]

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.

[tk0miya]

Good point. But -1 for changing interface. We have to give a good syntax to SPHINX_APIDOC_OPTIONS to improve it. Just idea, members,undoc-members,show-inheritance,special-members(__and__, __iand__, __or__, __ior__),exclude-members(__iter__, __call__) is compatible and a little readable to me.

[raabf]

Thanks for responding! That would actually introduce ( as an additional delimiter. I agree that this would work and that is prevents an interface change. It looks also intuitive and good readable.

However, that would introduce an additional syntax for the same thing, which is in general a bad thing, although the syntax is not that complicated. That would mean that we have to keep those two syntaxes in sync if the original syntax changes. Furthermore, the user have to look up two syntaxes, although both result in the same output.

So I would prefer to keep the original syntax, but it would be fine for me to extend the current syntax if we say its more important for not changing the interface.

Mhmm, just thinking loudly:

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

That would mix both. e.g. if there is a ,:, the rest of the string is sliced on ,: and not , anymore. The old syntax could be still used in the beginning. Would mean that the : syntax can be only be appended. That would allow both, but is a bit confusing.

[tk0miya]

Unfortunately, comma is used as a separator for both SPHINX_APIDOC_OPTIONSand some autodoc directive options. It means they're conflicted. IMO, it is difficult to make natural style options with original syntax of autodoc directive options.

[filip-halt]

Any updates on this?