sphinx creates an empty documentation

Question

Assume the following is the structure of my code:

   A/
       __init__.py
       B.py
    
  Run.py

I go ahead and install sphinx and numpydoc extension. Then I issue sphinx-quickstart and choose the default (don't separate the source and builder) then I have the following files:

   A/
      docs/
           conf.py
           index.rst
           static
           templates
      __init__.py
      B.py
  Run.py

Next step I edit the index.rst and add the followings:

    .. automodule:: Run
       :members:

Then I edit the conf.py as follows:

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

Then I cd into docs directory and issue make HTML however when I open index.html file I see no documentation and it is empty.

I searched all the posts in the internet and here but none of them work for me.

I would like to know can anyone tell me:

1- If what I am doing is correct?

2- Since I am using numpydoc convention in my docstring, can this be the reason why I do not see anything?

EDIT: I separated the project and source and run sphinx-apidoc -o ./source .. and this generates two more rst file for A.rst and modules.rst and I changed the index.rst accordingly however after running make HTML I receive warning no module name A and fail to import B from module A.

A/
      __init__.py
      B.py
      source/
             module.rst
             index.rst
             A.rst
Run.py

BTW I have added

'sphinx.ext.autodoc','sphinx.ext.napoleon'

to extension list in conf.py.

This is the content of my index.rst:

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   
   A
   modules   
   


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

From your description you haven't edited index.rst to include modules.rst. If `make html` ran without giving errors that should be the problem. From your directory/file structure description it isn't clear if Run.py and B.py are both on the same level inside the A directory. In any case, you are using [the same layout as this answer](https://stackoverflow.com/a/59951675) so check your steps against that and let us know how things went. — bad_coder, Aug 24 '20 at 01:19
@bad_coder I edited my question. Run.py is not inside the A. Run.py will run the B. I do not have modules.rst since I thought this is created using sphinx-apidoc and it is useful when you have multiple files and package and here I have only B.py inside A package. inside index.rst I have added the automodule:: Run and :members: — math, Aug 24 '20 at 01:27
@bad_coder the default is set to no. But shouldn't I link to python file that runs my package. Here Run.py runs B.py and I thoughts it should be ('../..') — math, Aug 24 '20 at 01:32
@bad_coder I followed your link in the first comment and did everything from scratch now in make HTML I see information about module A but nothing related to docstring or any documentation and I have some warning regarding the failing to import module A — math, Aug 24 '20 at 02:37
The example has a docs/source and docs/build. Your edit does not have a /docs directory. If you get any step or detail wrong something isn't going to work, so compare the example with what you did and find the differences. Notice that in every edit you make, you never give enough info to understand exactly what's wrong. That's one problem of deviating from the example. — bad_coder, Aug 24 '20 at 07:20

sphinx creates an empty documentation

0 Answers0