0

I am new to Sphinx, and have tried to follow the documentation and guidance from books and YouTube videos. My classes and functions are documented like using autodoc:

class Person:
'''
This class describes a person
'''
def __init__(self):
    self.name = ''
    self.birth_date = date.today()
    self.gender = ''

def set_date_of_birth(self, year: int, month: int, day: int):
    '''
    Sets the value of the birth date.
    :param year: The year.
    :param month: The month.
    :param day: The day.
    :return: None.
    '''
    self.birth_date = date(year, month, day)

After launching sphinx-quickstart and make html afterwards, an index.html is created that only contains empty Index, Module Index, and Search Page, but no reference to the code whatever.

conf.py contains extensions as follows:

extensions = [ 'sphinx.ext.autodoc',
           'sphinx.ext.doctest',
           'sphinx.ext.intersphinx'
          ]

Obviously something is wrong or missing, but what? The test project does not use virtual environment, but a global interpreter instead (Python 3.10, is this of importance?). The project itself is in PyCharm. I would be thankful for a working and comprehensible example.

Alex Konnen
  • 717
  • 6
  • 20
  • 3
    If using a [`/src` layout see this answer](https://stackoverflow.com/a/60159862) or see this other answer [if using a flat layout](https://stackoverflow.com/a/59951675). – bad_coder Dec 08 '22 at 11:49
  • 2
    @bad_coder Looks promising, starting my next attempt... – Alex Konnen Dec 08 '22 at 12:08
  • @bad_coder For option 1 (code files in 'src' folder): I copied everything from your sequence verbatim, an I am getting the following error: L:\TestSphinx\docs\source\index.rst:9: WARNING: toctree contains reference to nonexisting document ' modules' looking for now-outdated files... none found pickling environment... done checking consistency... L:\TestSphinx\docs\source\modules.rst: WARNING: document isn't included in any toctree File modules.rst was created. What could be wrong here? TIA. – Alex Konnen Dec 08 '22 at 15:55
  • 1
    You'd better take a look at real world examples (any main stream Python package, like https://github.com/pyasn1/pyasn1) to study how they put source code and documentation together. – Lex Li Dec 08 '22 at 16:05
  • I see, those were warnings, and the html files do have content. The output looks though very differently from the HTML in your answers, but these, I guess, are CSS things. Anyway, something is being generated, to start with. Thanks! – Alex Konnen Dec 08 '22 at 16:17
  • @AlexKonnen You want to start simple - both the examples I linked are correct, and they can't be more concise. I advise against LexLi's example because that's way too much code and files. If an error happens with the posts I linked it's always because the user deviated from the example. – bad_coder Dec 08 '22 at 18:10

0 Answers0