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 proj

Answer 1

I'll try answering by putting the "canonical" approach side-by-side with your case.

The usual "getting started approach" follows these steps:

1. create a doc directory in your project directory (it's from this directory the commands in the following steps are executed).

2. sphinx-quickstart (choosing separate source from build).

3. sphinx-apidoc -o ./source ..

4. 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`

---

---

Now compare the above with what you have - from what you shared in your question:

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

---

---

Your error stacktrace says it couldn't find the module 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.

---

---

You may care to notice the signatures of the sphinx commands at play:

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.