Sphinx does not read my function docString?

Question

I tried to auto docstring every module functions inside my project, but sphinx-apidoc does not read my function and doc string.

my project structure is like this

mktpip
├── docs
│   ├── Makefile
│   ├── build
│   ├── make.bat
│   └── source
│       ├── _static
│       │   └── logo.jpg
│       ├── _templates
│       ├── conf.py
│       ├── index.rst
│       └── reference
│           ├── me.rst
│           └── modules.rst
├── mktpip
│   ├── __init__.py
│   ├── __init__.pyc
│   └── me
|.      |- my_module.py
│       └── __init__.py
├── run.py
├── setup.cfg
└── setup.py

The source that I tried to auto-doc from is at mktpip/me/my_module.py that has a simple function like this

def my_module(a,b):
    """Calculate two number
    
    Args:
        a (int): operand 1
        b (int): operand 2
    
    Returns:
        int: sum of a + b
    """
    return a+b

To auto docstring, I performed the following steps:

(venv) ➜  mktpip copy git:(dev) ✗ sphinx-apidoc -f -o docs/source/reference mktpip/me
Creating file docs/source/reference/me.rst.
Creating file docs/source/reference/modules.rst.

Then, I generated the HTML from *.rst files

(venv) ➜  docs git:(dev) ✗ make clean && make html
Removing everything under 'build'...
Running Sphinx v1.8.5
making output directory...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 31 source files that are out of date
updating environment: 31 added, 0 changed, 0 removed
/Users/narun/Documents/mktpip/venv/lib/python2.7/site-packages/sphinx/util/nodes.py:94: FutureWarning:                                                                                                                                        
   The iterable returned by Node.traverse()
   will become an iterator instead of a list in Docutils > 0.16.
  for classifier in reversed(node.parent.traverse(nodes.classifier)):

Then, I open an index.html file and found it does not read my function of module me

(venv) ➜  docs git:(dev) ✗ open build/html/index.html

This is what the output:

There is no my function my_module() and its docString.

Inside conf.py, I added

docs_dir = os.path.dirname(os.path.dirname(__file__))
sys.path.insert(0, docs_dir)

In addition to above, here content of me.rst

me package
==========

Submodules
----------

me.my\_module module
--------------------

.. automodule:: mktpip.me.my_module
    :members:
    :undoc-members:
    :show-inheritance:


Module contents
---------------

.. automodule:: mktpip.me
    :members:
    :undoc-members:
    :show-inheritance:

What went wrong with this? Please kindly help me, thanks.

You didn't show the content of `me.rst` and it is strange that you put `my_module(a,b):` inside the `__ init__.py`. Try putting `my_module(a,b)` in its own module (that is not an __ init__.py), generate the `me.rst` again with `sphinx-apidoc` and rerun `make html`. — bad_coder, Aug 14 '20 at 09:04
`index.html` is an index page, not documentation of your module. Module documentation should be in `reference/me.html`. — Steve Piercy, Aug 14 '20 at 09:20
@bad_coder, I tried putting my function `my_mdoule()` in the other file beside `__init__.py` already, and re-generated document, but the result the same. I have edited question to add some more details. Thanks :) — Houy Narun, Aug 14 '20 at 10:14
@StevePiercy, my `index.rst` includes `reference/modules`. `modules` already automatically include `me`. Thanks :) — Houy Narun, Aug 14 '20 at 10:17
@HouyNarun try changing this line `docs_dir = os.path.dirname(os.path.dirname(__file__))` to go 2 levels down like so: `sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))`. The line is taken relative to where `conf.py` is and you want to point it below the package you are trying to import. — bad_coder, Aug 14 '20 at 10:24
@HouyNarun looking at the docs for your line [`os.path.dirname(__file__)`](https://docs.python.org/2/library/os.path.html#os.path.dirname) you are only passing the directory name of where `__file __` (conf.py) is placed. Please notice the difference between this and the comment above. — bad_coder, Aug 14 '20 at 10:44
@HouyNarun You asked this question twice before, [here](https://stackoverflow.com/questions/61060960) and [here](https://stackoverflow.com/questions/61986690). Perhaps you would like this [getting started example](https://stackoverflow.com/questions/59903051). — bad_coder, Aug 14 '20 at 11:12
@bad_coder, I have changed in `conf.py` to ```sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))``` already, but it still does not work. Regarding to my previous question, I have deleted one already thanks. — Houy Narun, Aug 15 '20 at 04:24

Sphinx does not read my function docString?

0 Answers0