I am running Sphinx on a rst
file containing automodule
but it does not seem to have any effect.
Here are the details: I have a Python project with a file agent.py
containing a class Agent
in it. I also have a subdirectory apidoc
with a file agent.rst
in it (generated by sphinx-apidoc
):
agent module
============
.. automodule:: agent
:members:
:undoc-members:
:show-inheritance:
I run sphinx with sphinx-build -b html apidoc apidoc/_build
with the project's directory as the current working directory.
To make sure the Python files are found, I've included the following in apidoc/conf.py
:
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
It runs without errors but when I open the resulting HTML file it only shows "agent module" and everything is blank. Why isn't it showing the class Agent
and its members?
Update: the original problem was likely caused by the fact that I had not included sphinx.ext.autodoc
in conf.py
. Now that I did, though, I get warnings like:
WARNING: invalid signature for automodule ('My Project.agent') WARNING: don't know which module to import for autodocumenting 'My Project.agent' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name) WARNING: autodoc: failed to import module 'agent'; the following exception was raised: No module named 'agent'
I'll try answering by putting the "canonical" approach side-by-side with your case.
The usual "getting started approach" follows these steps:
create a doc
directory in your project
directory (it's from this directory the commands in the following steps are executed).
sphinx-quickstart
(choosing separate source
from build
).
sphinx-apidoc -o ./source ..
make html
This would yield the following structure:
C:\Project
|
| agent.py
|
|---docs
| | make.bat
| | Makefile
| |
| |---build
| |
| |---source
| | conf.py
| | agent.rst
| | index.rst
| | modules.rst
In your conf.py
you'd add (after step 2):
sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
and in index.rst
you'd link modules.rst
:
Welcome to Project's documentation!
================================
.. toctree::
:maxdepth: 2
:caption: Contents:
modules
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
C:\Project
|
| agent.py
|
|---apidoc
| | agent.rst
| | conf.py
| |
| |-- _build
You ran:
sphinx-build -b html apidoc apidoc/_build
and in your conf.py
:
sys.path.insert(0, os.path.abspath('.'))
agent
. That's probably because you didn't go 1 level down in your conf.py
(it's pointing to the path with .rst
, not the path with .py
), this should work:
sys.path.insert(0, os.path.abspath('..'))
. Also, if you didn't manually edit/connect your modules.rst
in your index.rst
you are likely to only see that module.
sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH>
sphinx-build [options] <sourcedir> <outputdir> [filenames …]
<sourcedir>
refers to where .rst
are, and <MODULE_PATH>
to where .py
are. <OUTPUT_PATH>
to where .rst
are placed, and <outputdir>
to where .html
are placed.
Please also notice, you mentioned: "the project's directory as the current working directory." I've seen "working directory" mentioned in sphinx threads on stackoverflow, interchangeably as both the Project
base directory, or the docs
directory. However, if you search the Sphinx documentation for "working directory" you'll find no mention of it.
Finally, there is an advantage to using the file/directory structure of the "getting started approach". It basically "puts you on the same page" with most threads on the Sphinx tag, and that way alleviates the mental work of mapping the cases to different directory/file structures.
I hope this helps.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With