Sphinx's autodoc's automodule having apparently no effect
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 yourproject
directory (it's from this directory the commands in the following steps are executed).sphinx-quickstart
(choosing separatesource
frombuild
).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`
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.
Sphinx can't find the root module of my project
In your conf.py, put sys.path.insert(0, "..")
. The ../ relative path navigates to the parent directory. Since conf.py is located in docs/, the parent directory of docs/ is the root of your project. This way, sphinx
will be able to access your project files and it will be able to import your modules.
FileNotFoundError: [Errno 2] when using sphinx and autodoc
Finally I figured out something that worked for me. Beforehand, I need to clarify something: in one of python files located in ../../
from my source
directory, the code is reading an excel file from this path ./input/input.xlsx
. I figured out that defining a hard coded path is the source of this issue. So I fixed it with following code:
directory_path = os.path.dirname(os.path.abspath(__file__))
new_path = os.path.join(directory_path, "input.xlsx")
Related Topics
Why Is Using Thread Locals in Django Bad
Converting List of Tuples into a Dictionary
Getting Values from Object Oriented Tkinter
Builtin Function Not Working with Spyder
Using Print() (The Function Version) in Python2.X
Access to Table Objects on Webpage Using Python Selenium
Python Progression Path - from Apprentice to Guru
Can One Get Hierarchical Graphs from Networkx with Python 3
How to Change Effective Process Name in Python
High Performance Fuzzy String Comparison in Python, Use Levenshtein or Difflib
Why Do Many Examples Use 'Fig, Ax = Plt.Subplots()' in Matplotlib/Pyplot/Python
Difference Between Parsing a Text File in R and Rb Mode
Regular Expression Usage in Glob.Glob
Python Variables as Keys to Dict
How Do Python Functions Handle the Types of Parameters That You Pass In
Oserror: [Winerror 193] %1 Is Not a Valid Win32 Application