10

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?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
AME
  • 2,499
  • 5
  • 29
  • 45
  • 1
    Examples in the code base, like, code after a `__main__`? Or doctests (you know, tests in a docstring) ? – Pierre GM Sep 12 '12 at 15:29
  • 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 Sep 12 '12 at 15:34
  • 1
    (1) check whether you have some code in the `__main__`; (2) if you're not using the [`doctest`](http://sphinx.pocoo.org/ext/doctest.html) extension, you should befine. Check your configuration file to make sure. – Pierre GM Sep 12 '12 at 15:48
  • 3
    The files automatically created by `sphinx-apidoc` will use the [sphinx.ext.autodoc](http://sphinx.pocoo.org/ext/autodoc.html) extension. This extension evaluates definitions to obtain their `__doc__` attribute. So that can also be a cause of warnings. – Pedro Romano Sep 12 '12 at 23:22

2 Answers2

14

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.

mzjn
  • 48,958
  • 13
  • 128
  • 248
3
def main():

    print('hello world')

if __name__ == '__main__':

    main()

This way your code will not be run.

Miriam Farber
  • 18,986
  • 14
  • 61
  • 76
Anthony Petrillo
  • 365
  • 1
  • 4
  • 13