readthedocs / sphinx-autoapi

A new approach to API documentation in Sphinx.
https://sphinx-autoapi.readthedocs.io/
MIT License
415 stars 126 forks source link

Cannot omit undoc-members when specifying options #456

Closed mfncooper closed 1 week ago

mfncooper commented 2 weeks ago

This is rather a bizarre issue that I'm seeing with sphinx-autoapi version 3.1.1.

Simple test case with directory structure as follows:

./docs
./docs/index.rst
./docs/Makefile
./docs/conf.py
./tc
./tc/__init__.py

init.py contains only:

class MyClass:
    """ This is my base class. """

    def a_method(self):
        """ This is a method. """
        pass

and conf.py is as follows:

project = 'TestCase'
author = 'Martin F N Cooper'
copyright = '2024, ' + author

extensions = [
    'autoapi.extension'
]
autoapi_dirs = ['../tc']

# The following is the default set of options from the docs. This works.
#autoapi_options = [ 'members', 'undoc-members', 'private-members', 'show-inheritance', 'show-module-summary', 'special-members', 'imported-members' ]

# The following is the same list but without 'undoc-members'. This breaks.
autoapi_options = [ 'members', 'private-members', 'show-inheritance', 'show-module-summary', 'special-members', 'imported-members' ]

templates_path = ['_templates']

When running make html in the docs directory, I get:

Extension error (autoapi.extension):
Handler <function run_autoapi at 0x10783f700> for event 'builder-inited' threw an exception (exception: [Errno 2] No such file or directory: '/Users/<rest_of_path>/docs/autoapi/index.rst')

As noted in the conf.py comments, it works if I use the complete list of defaults. If I omit the options specification entirely, it behaves the same as if I specify those defaults (not surprisingly). But if I specify any options, I must include 'undoc-members' or it fails. This is particularly odd since, in this example, I don't actually have any undocumented members.

sachahu1 commented 2 weeks ago

I believe this is a duplicate of #448 and #441.

See this comment

AWhetter commented 1 week ago

Closing as a duplicate of #448. You can omit undoc-members but you must document the module, otherwise it is considered undocumented and therefore not rendered.