Sphinx Inplace

.. toctree:: :maxdepth: 2

file_tree.rst
rst_generator.rst
doc_guide/index.rst

Sphinx provides powerful functions, but provides few functions about edit doc inplace. We have to generate rst files and edit the rst files. This package provides a new procedure, that we can write code just in the same directory with python files.

The code was firstly used in pyminer.

This package aims to replace sphinx-apidoc .

The source docstring is parsed and then generate doc with levels.

In a normal sphinx project, developers have to maintain *.rst directory. Sphinx provides series of directors to generate html from python source code.

sphinx-apidoc is required to create *.rst file structure. However, if python structure changed, developers have to update *.doc file structure manually.

This tool do not need apidoc , and all the doc will automatically generated from python code.

Usage

Please see the demo directory for more information.

Tips

__init__.py are important files, the same as in python project. Directory with __init__.py will be regarded as the python package, and the package template will be used.

All the assets can be put in the same directory as *.py files. The assets will be copy to the docs/rst directory.

Thus, relative path is available in *.rst and *.md files.

If you are not satisfied with the auto generated *.rst file, you can create the {filename}.rst file at the same directory with the {filename}.py. The new rst file will cover the autogenerated rst file.