Stack Exchange
Generating documentation from docstring using Sphinx
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:

my_project.py has the main function. So I commented out the main function, but still there's no documentation generated.
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.

Does this answer your question? https://stackoverflow.com/a/48370291/2214933

Yes, that did the trick! Thanks a tonne. Never knew a missing __init__.py was the cause for this.

@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 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.

But I guess that's what sphinx-apidoc should take care of, right?

@ghost have you gotten this to work in the meanwhile?

@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.

Though I'm still unsure why autodoc and sphinx require actual code to run when all they do (I suppose) is parse.

@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 that's where you'll see that best.
