readthedocs / readthedocs/sphinx-autoapi

Parses first element of if __name__ == '__main__' block

Open
#429 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
494
Forks
147
Avg merge
9m
Merged PRs (30d)
1

Description

If a module has an if __name__ == '__main__: block, the first element is analysed and its documentation is generated. The next ones are ignored. This is regardless if it the first a variable or a function.

Uses python 3.11, sphinx-autoapi 3.0.0, Sphinx 7.2.6

I expect the behaviour to be that everything in if __name__ == '__main__: blocks would be ignored like sphinx-autodoc does.

Minimal working example:
Analysing

def normal_function():
    """
    Function with docstring
    """
    pass

if __name__ == '__main__':
    def new_example():
        """
        This function will appear in the docs
        """
        pass
    this_variable_is_ignored = 52

gives

IV50eJKtYclZcZur

When variable is first, this appears in the docs while the function new_example is ignored.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No source file or test is named. Start by reproducing the issue with the supplied Python example under the stated Python, Sphinx, and sphinx-autoapi versions, then compare the generated output with sphinx-autodoc's behavior. Done means every element inside an if __name__ == '__main__': block is excluded, regardless of whether the first element is a variable or function.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.