Prevent Sphinx from executing the module

Question

I am trying to do python documentation generation with Sphinx. The problem is that sphinx-build ends up executing the module/evaluating anything in global scope. Is there a reason it does this? And does anyone know of a flag that can be set to disable this?

It seems like Sphinx is trying to do code-coverage or something equivalent, which is definitely not what I want it doing. Normally this wouldn't be an issue, but a particular set of modules are very specific to an environment.

Yes it's normal the modules are imported by sphinx when autodoc. It has to do that in order to retrieve the docstrings, classes and functions info, etc. Could you provide a little bit more info? How does it stop? What is the message? etc. — cblab
– cblab, Commented Jun 13, 2012 at 0:19

David Wolever · Accepted Answer · 2012-06-13 00:18:41Z

6

Sphinx evaluates everything in the global scope because the autodoc plugin imports modules, and importing a module evaluates everything in the global scope.

To stop this, either:

Disable the autodoc plugin (search for autodoc in the sphinx config file), or
Guard the code you don't want executed with something like if __name__ == "__main__": do_stuff()

edited Jun 13, 2012 at 0:18

answered Jun 13, 2012 at 0:11

David Wolever

156k94 gold badges365 silver badges513 bronze badges

Sign up to request clarification or add additional context in comments.

3 Comments

djp Over a year ago

Ah -- yes, that conveniently works, since the few globals I do have are only relevant to the module if it is being run as a script. I can place them inside that statement. Thanks!

cglacet Over a year ago

Is it possible to use autodoc without importing the module? For example if we only need autodoc to read/parse docstring (not containing any tests or fancy code interpretation of any kind, just plain text). That looks a bit overkill to import all our project dependencies to read docstrings.

mnesarco Over a year ago

I think that executing the code just to get docstrings is a very bad design, it converts buildtime into runtime. They could just parse the code and extract docstrings like any other code documentation generator in the known universe.

Collectives™ on Stack Overflow

Prevent Sphinx from executing the module

1 Answer 1

3 Comments

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

3 Comments

Related