Generating documentation from docstring using Sphinx

Viewed 1602

I have my project with the following structure:

my_project
├── README.md
├── docs
│   ├── Makefile
│   ├── build
│   │   ├── doctrees
│   │   └── html
│   ├── make.bat
│   ├── output-docs
│   │   ├── _sources
│   │   ├── _static
│   │   ├── index.html
│   │   ├── my_project.html
│   │   ├── modules.html
│   │   └── ...
│   └── source
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       ├── config_parser.rst
│       ├── index.rst
│       ├── my_project.rst
│       └── modules.rst
├── input
│   ├── a.csv
│   └── b.csv
├── my_project
│   ├── config.yml
│   ├── config_parser.py
│   ├── my_project.py
│   └── utils
│       └── my_utility.py
...

I have the docstrings corresponding to the various functions in my_project.py and my_utility.py. I wanted to generate documentation using Sphinx. So I did the following:

mkdir docs
cd docs
sphinx-quickstart

I provided the options as asked for (author, version, etc.). Then I modified the source/config.py as follows (I'm including only the modifications):

import os
import sys
sys.path.insert(0, os.path.abspath('../../'))

extensions = ['recommonmark', 'sphinx.ext.autodoc']

Then I used sphinx-apidoc, followed by a sphinx-build. The following is the code (this was run inside the docs folder):

sphinx-apidoc -f -o source/ ../my_project
sphinx-build source output_docs

However I get a couple of errors:

reading sources... [100%] config_parser
WARNING: autodoc: failed to import module 'config_parser'; the following exception was raised:
No module named 'config_parser'
looking for now-outdated files... none found
pickling environment... done

checking consistency... /Users/my_user/Projects/my_project/docs/source/modules.rst: WARNING: document isn't included in any toctree

Also, the HTML docs are included in the output-docs. But when I open index.html, I see my_project, but no modules or docstrings are included.

I don't know what I'm missing. I've gone through some of the documentation, and some questions like Generate sphinx docu from docstrings not working, but I guess I missed something important. Any help would be great.

EDIT 1:

As suggested by @Steve, I added an __init__.py to both my_project/my_project and my_project/my_project/utils. Now, I'm getting the document generated for the functions in my_project/my_project/utils/my_utility.py and my_project/my_project/config_parser.py. However, the documentation is still missing for my_project/my_project/my_project.py.

I thought that the plausible reasons might be:

  1. my_project.py has the main function. So I commented out the main function, but still there's no documentation generated.
  2. my_project.py has the same name as its parent directory, my_project. So I renamed it, but still not documentation was generated.

Any guidelines on how to progress would be very helpful.

0 Answers
Related