Sphinx in Windows doesn't create docs for modules

Question

I am trying to create documents for my project using sphinx. My project structure looks like this.

Project_root
|-docs
  |-_build
  |-_static
  |-_template
  |-rst
  |-conf.py
  |-Makefile
  |-make.bat
  |-index.rst
|-modules
  |-__init__.py
  |-module1.py
  |-module2.py

I got this dir setup by running sphinx-quickstart in my docs dir and modules dir contains my program models that need to create docs. Files contail docstring to create automatic docs like this.

"""Class represent a sentence of a comment of a bug report

Parameters
----------
sentence_id : str
    sentence_id is a combination of turn_id and the sequence number
    (ex: 1.3 means turn 1 and 3rd sentence of the turn)
text : str
    orginal sentence text as appeared in the bug report
cleaned_text : str
    cleaned text after removing irrelevant characters, stop words,
    turning to lower case and lemmatizing
tags :list of str
    tags indicate the type of the sentence (description, clarification,
    plan, resolution) and/or picked by certain algorithm
"""

I have changed the path in conf.py as follows.

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

When I run sphinx-apidoc -o rst ..\models it only create models.rst and modules.rst. No rst were created for module1.py and module2.py.

I wonder what is going on with my configuration.

Edit: I forgot to add `init.py in my dir tree.

modules is not a Python package because it lacks an __init__.py file, and Sphinx can only import Python packages, so add an empty __init__.py. Also try abspath('../') because Python does not care about Windows backslashes for directories. — Steve Piercy
@Steve Piercy: Thank you for pointing out my mistake in abspath. This actually solved my problem. Care to put this as your answer so that I could accept. However, I have noticed that in tutorials when running the sphinx-apidoc it creates .rst files for each module. I don't get those. But documentation is there. Any ideas what is going on here. — akalanka
Please create a new question, instead of adding a new question in a comment. Include the full command with appropriate options. — Steve Piercy

Steve Piercy Steve Piercy · Accepted Answer · 2019-11-10T03:13:04

0

votes

Try abspath('../') because Python does not care about Windows backslashes for directories.

Sphinx in Windows doesn't create docs for modules

1 Answers