Does Sphinx run my code on executing 'make html'?

9
votes

I inherited a rather large codebase that I want to create HTML documentation for. Since it is written in Python I decided to use Sphinx because the users of the code are accustomed to the design and functionality of the Python documentation that's created with Sphinx. I used the command sphinx-apidoc to automatically create the .rst files. I imported the module path into sys.path so that Sphinx can find the code.

So far so good. However, when I try to create the HTML using the command make html, there are many tracebacks popping up and some of the examples in the codebase seem to get executed. What can be the reason for that and how can I prevent that from happening?

2
pythonpython-sphinx
Examples in the code base, like, code after a __main__? Or doctests (you know, tests in a docstring) ? - Pierre GM
Good question. I hesitate to run it again. The exact command for sphinx-apidoc was: sphinx-apidoc -f -F -o . ../src follows by make html. Would that initiate the execution of doctests? If so, how can I prevent it from doing that? - AME
(1) check whether you have some code in the __main__; (2) if you're not using the doctest extension, you should befine. Check your configuration file to make sure. - Pierre GM
The files automatically created by sphinx-apidoc will use the sphinx.ext.autodoc extension. This extension evaluates definitions to obtain their __doc__ attribute. So that can also be a cause of warnings. - Pedro Romano

2 Answers

13
votes

When using autodoc, Sphinx imports the documented modules, so all module-level code is executed. This happens every time you do "make html". In that sense, Sphinx does "run" your code.

You may have to organize your code a bit differently to make the errors go away (move module-level code to functions). See this question for an example of what can happen.

This is my guess but it may not be the whole story. It's hard to say more without additional information.

3
votes
def main():

    print('hello world')

if __name__ == '__main__':

    main()

This way your code will not be run.