python - Sphinx's autodoc's automodule having apparently no effect

Question

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'

You module must be in a Python package. Put it in a folder which also contains an __init__.py, and adjust conf.py and your reST as needed, e.g., mypackage.agent. — Steve Piercy
I don't know what the problem is here, but it is not true that the module must be in a package. It is possible to have a single agent.py module and no __init__.py. — mzjn
Indeed, that did not seem to make a difference. I've added an update to the question, please take a look. — user118967

bad_coder bad_coder · Accepted Answer · 2020-01-28T15:08:41

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('.'))

agentconf.py.rst.pysys.path.insert(0, os.path.abspath('..'))modules.rstindex.rst

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.

python - Sphinx's autodoc's automodule having apparently no effect

1 Answers