3

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.

ghost
  • 1,107
  • 3
  • 12
  • 31
  • Does this answer your question? https://stackoverflow.com/a/48370291/2214933 – Steve Piercy Aug 19 '20 at 12:47
  • 1
    Yes, that did the trick! Thanks a tonne. Never knew a missing `__init__.py` was the cause for this. – ghost Aug 19 '20 at 13:03
  • @StevePiercy However, there's still an issue. I can see the methods in `config_parser.py` and the ones under `utils.my_utils.py`. However, the methods in `my_project.py` are still not visible. – ghost Aug 19 '20 at 13:09
  • @ghost that's a different issue, you have to make sure you include the parts of the module you want in an automodule directive the .rst file. Your original error was being issued by the `toctree`, you probably haven't included the `my_project.py` in the `toctree` but we have no way of knowing that because you didn't include the needed files, and that's a different question altogether. – bad_coder Aug 19 '20 at 13:32
  • But I guess that's what `sphinx-apidoc` should take care of, right? – ghost Aug 19 '20 at 13:40
  • @ghost have you gotten this to work in the meanwhile? – bad_coder Sep 12 '20 at 17:17
  • @bad_coder yes. Turns out that `autodoc` needs to run modules before generating a doc. The issue was - I ran my code on an IDE (with all environment variables being set), but generated doc using terminal. Since the `PYTHONPATH` was not modified on terminal, `Sphinx` couldn't do the imports, and thus failed. – ghost Sep 12 '20 at 17:40
  • Though I'm still unsure why `autodoc` and `sphinx` require actual code to run when all they do (I suppose) is parse. – ghost Sep 12 '20 at 17:42
  • 1
    @ghost they don't just parse, Sphinx and `autodoc` import and run the modules. Otherwise attributes wouldn't be set on classes, imports wouldn't be made, variables wouldn't have initialized values, and so on...If you ever try to document an [argparse or script](https://stackoverflow.com/questions/34570114) that's where you'll see that best. – bad_coder Sep 12 '20 at 17:54

0 Answers0