Any simple python module documentation generator that does not try to run/import code?

Question

I have a pretty large project with lot of packages, modules and dependencies. I want to generate the API doc of a few modules in the project. The documentation is already added as doc-strings.

I tried using sphinx but I am plagued with import errors. And the configuration required to avoid these import errors is just too much for my need.

Is there a doc generator that would take a module, parse the doc strings in it and produce the output, either in markdown, rst or html in a good readable format?

I also tried pdoc... which comes pretty close. But it also tries to import the module — Nithin, Dec 21 '13 at 21:42

score 1 · Answer 1 · answered Dec 21 '13 at 20:53

1

Epydoc:

--parse-only, --introspect-only By default, epydoc will gather information about each Python object using two methods: parsing the object's source code; and importing the object and directly introspecting it. Epydoc combines the information obtained from these two methods to provide more complete and accurate documentation. However, if you wish, you can tell epydoc to use only one or the other of these methods. For example, if you are running epydoc on untrusted code, you should use the --parse-only option.

answered Dec 21 '13 at 20:53

dstromberg

6,954
1
26
27

Does epydoc support python3? – Nithin Dec 21 '13 at 22:08
Scratch that.. even if python3 is supported, epydoc doesnt work for me... :( – Nithin Dec 21 '13 at 22:20

score 0 · Answer 2 · edited May 23 '17 at 12:03

0

A solution could be to mock the not wanted modules (see also: here). Epydoc was no solution for me and has not been maintained for long time. I'm not sure if it is too much configuration required for your needs, but imho a very straightforward solution.

import mock

MOCK_MODULES = ['numpy', 'matplotlib', ...]
for mod_name in MOCK_MODULES:
    sys.modules[mod_name] = mock.Mock()

edited May 23 '17 at 12:03

Community

1
1

answered Dec 21 '13 at 21:03

knx

398
3
21

I saw this... too many modules (both user created and otherwise). Would this go in the actual source files or in the sphinx conf file?? – Nithin Dec 21 '13 at 22:02
Hey, afaik at the top of your conf.py. You should take a look at the following [post](http://blog.rtwilson.com/how-to-make-your-sphinx-documentation-compile-with-readthedocs-when-youre-using-numpy-and-scipy/) or this [so-post](http://stackoverflow.com/questions/15889621/sphinx-how-to-exclude-imports-in-automodule). Hope this helps.. – knx Dec 21 '13 at 22:09
Tried doing that... like I said too many imports. For example, there is a model class that uses mongoengine. Now I have to add all the mongo engine field classes to MOCK_MODULES and I dont even want to generate doc for models.py. The reason I dont want to use sphinx. – Nithin Dec 21 '13 at 22:18

score 0 · Answer 3 · answered Jan 10 '19 at 16:13

pdoc, but it imports the modules it documents and parses ASTs only in case of __init__() method to discover instance variables.

If you are plagued with import errors, you may be doing something wrong. A common idiom in Python is to wrap any module-level code that is not to be executed when the module is simply imported behind this if-guard:

if __name__ == "__main__":
    # This will only be run when the module is run,
    # but not when it is imported
    ...

See also: What does if __name__ == "__main__": do?

Any simple python module documentation generator that does not try to run/import code?

3 Answers3