Python Sphinx recorded using the stepped pit

description

After use pip install sphinx, follow the tutorial built a new py file, as follows

# run.py
def run(name):
    """
    this is how we run
    :param name name of people who runs
    """
    print(name, 'is running')

Then a new directory using the sphinx sphinx-quickstart new environment, that the directory structure is as follows:

- doc
    - Makefile
  - build/
  - make.bat
  - source/
- run.py

At this time, into the source directory, file path conf.py added as follows:

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))

Then execute the following command in the doc:

make html

or

sphinx-build -b html ./doc/source ./doc/build

Both commands can be found in the normal production of the template document, but did not generate comments; html that is generated, but no code comments / API Documentation

Try to resolve

1

Start previous version is inconsistent, then re-built virtualenv, or not;

Docker using a mirror, retry, the result is the same error

2

Try to see the unofficial course, also you need to change index.rst found in the source;

For example, our code file is run.py , need to be added to his index.rst as follows (run is the module name):

API
===
.. automodule:: run
   :members:

Executed again found that there is wrong, but not the same tips: tips

Unknown directive type “automodule” or “autoclass”

3

Google it, find a need to change the configuration of a place; located conf.py , the increase in an extended ...... follows:

extensions = [
        'sphinx.ext.autodoc'
]

Here reference https://stackoverflow.com/questions/13516404/sphinx-error-unknown-directive-type-automodule-or-autoclass

Try again, finally succeeded ...

Impressions ......

Maybe I was not detailed enough to see the document, but it is not very friendly feeling ah