Automatically Generating Documentation for All Python Package Contents

后端 未结 4 2132
醉酒成梦
醉酒成梦 2020-12-04 09:03

I\'m trying to auto-generate basic documentation for my codebase using Sphinx. However, I\'m having difficulty instructing Sphinx to recursively scan my files.

I have

相关标签:
4条回答
  • 2020-12-04 09:41

    Note

    For Sphinx (actually, the Python interpreter that executes Sphinx) to find your module, it must be importable. That means that the module or the package must be in one of the directories on sys.path – adapt your sys.path in the configuration file accordingly

    So, go to your conf.py and add

    import an_example_pypi_project.useful_1
    import an_example_pypi_project.useful_2
    

    Now your index.rst looks like:

    .. toctree::
       :glob:
    
       example
       an_example_pypi_project/*
    

    and

    make html

    0 讨论(0)
  • 2020-12-04 09:43

    You can try using sphinx-apidoc.

    $ sphinx-apidoc --help
    Usage: sphinx-apidoc [options] -o <output_path> <module_path> [exclude_paths, ...]
    
    Look recursively in <module_path> for Python modules and packages and create
    one reST file with automodule directives per package in the <output_path>.
    

    You can mix sphinx-apidoc with sphinx-quickstart in order to create the whole doc project like this:

    $ sphinx-apidoc -F -o docs project
    

    This call will generate a full project with sphinx-quickstart and Look recursively in (project) for Python modules.

    Hope this helps!

    0 讨论(0)
  • 2020-12-04 09:50

    From Sphinx version 3.1 (June 2020), if you're happy to use sphinx.ext.autosummary to display summary tables, you can use the new :recursive: option to automatically detect every module in your package, however deeply nested, and automatically generate documentation for every attribute, class, function and exception in that module.

    See my answer here: https://stackoverflow.com/a/62613202/12014259

    0 讨论(0)
  • 2020-12-04 10:04

    Perhaps apigen.py can help: https://github.com/nipy/nipy/tree/master/tools.

    This tool is described very briefly here: http://comments.gmane.org/gmane.comp.python.sphinx.devel/2912.

    Or better yet, use pdoc.


    Update: the sphinx-apidoc utility was added in Sphinx version 1.1.

    0 讨论(0)
提交回复
热议问题