Python: How I can define in sphinx which .rst file

2019-06-26 07:25发布

问题:

How I can define in sphinx which .rst files and directories should be used?

I want to include an automatic documentation generator in my testing/building/documentation script. sphinx-quickstart was executed in my workspace and created an index.rst-file. As sphinx uses restructured text files for documentation I navigated through the workspace and create them manually with sphinx-autogen. It resulted into the tasks.rst file (see below).

When I use 'make html' I get several warnings:

WARNING: invalid signature for automodule (u'tasks/add_to_config')

WARNING: autodoc can't import/find module 'tasks.add_to_config', it reported error: "No module named wl_build.tasks", please check your spelling and sys.path

WARNING: don't know which module to import for autodocumenting u'tasks/add_to_config' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)

...

My index.rst

Welcome to build's documentation!
====================================

Contents:

.. toctree::
   :maxdepth: 2

.. automodule:: tasks/add_to_config
   :members:

.. automodule:: tasks/build_egg
   :members:   

tasks.rst

tasks Package
=============

:mod:`tasks` Package
--------------------

.. automodule:: tasks.__init__
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`add_to_config` Module
---------------------------

.. automodule:: tasks.add_to_config
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`build_egg` Module
-----------------------

.. automodule:: tasks.build_egg
    :members:
    :undoc-members:
    :show-inheritance:

回答1:

Try replacing the / characters in your index.rst file with periods (.)

like this:

Welcome to build's documentation!
====================================

Contents:

.. toctree::
   :maxdepth: 2

.. automodule:: tasks.add_to_config
   :members:

.. automodule:: tasks.build_egg
   :members:  

See if that helps.

If Sphinx still can't find the code to document, then you'll probably need to modify your PYTHONPATH or alter sys.path in your conf.py file in order to help Sphinx find what it's looking for.