文档字符串未填充 Sphinx 文档

Question

I am trying to generate Sphinx documentation for my Python application. Originally I had a complex structure as follows...

venv
docs
├───source
├───├───_static
├───├───_templates
├───├───conf.py
├───├───index.rst
├───├───modules.rst
├───├───...
├───build
├───make.bat
├───Makefile
├───MyCode
├───├───Utilities
│   │   └───class1.py
├───├───Configurations
│   │   ├───Archive
│   │   ├───API1_Configurations
│   │   │   ├───Config1.ini
│   │   ├───API2_Configurations
│   │   │   ├───Config2.ini
│   │   ├───API3_Configurations
│   │   │   ├───Config3.ini
│   │   ├───API4_Configurations
│   │   │   ├───Config4.ini
├───├───APIs
│   │   ├───API1
│   │   │   ├───Class1.py
│   │   │   ├───Class2.py
│   │   ├───API2
│   │   │   ├───Class1.py
│   │   │   ├───Class2.py
│   │   │   ├───Supporting
│   │   │   │   └───Class1.py
│   │   ├───API3
│   │   │   ├───Support
│   │   │   │   ├───SupportPackage1
│   │   │   │   ├───Support Package2
│   │   │   │   │   └───Class1.py
│   │   │   │   └───__pycache__
│   │   │   └───Class1.py

In this case, my source code exists in ./docs/MyCode.

I am using...

• Python 3.8
• Sphinx 4.2 (although I've tried with many versions)
• NumPy docstrings

I have...

• Added the following extensions
  • sphinx.ext.autodoc
  • sphinx.ext.apidoc
  • sphinx.ext.napoleon
• Pointed conf.py to my code using both a relative path and absolute path (relative path being ../MyCode ).

For some reason, the closest I can get to actually populating the HTML pages with my documentation is simply having the classes in the index toctree . They link out to blank html pages without my Python docstrings.

Does anyone have any idea why it won't grab my docstrings??

Answer 1

Ok... feeling pretty dumb about this, but it was just cause of the warnings.

Sphinx requires that the package is a fully installable package in the sense that when it is placed in the sphinx package, it should be able to compile. I had some absolute references in my import statements which caused my program to fail. As such, the actual docstrings in my program could not be pulled while the names of the classes still showed in my sphinx html.