11

I started working on a python module and wanted to document the code "in place". So i set up sphinx in a subdirectory with sphinx-quickstart resulting in this directory structure (only the files i edited are shown):

  • myproject/
    • __init__.py
    • main.py
  • docs/ (sphinx directory)
    • build/
    • source/
      • conf.py
      • index.rst
  • setup.py

My index.rst contains:

Welcome to My Module's documentation!
=====================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

.. automodule:: myproject
    :members:


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

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

When i run 

make html

i get a documentation that is missing the automodule part allthough i documented every class and every method in main.py like this:

class Thing:
    """This class represents Things

    :param color: how the thing should look like
    """

    def __init__(self, color):
        pass

    def color(self):
        """Tells you the color of the thing.

        :returns: Color string
        :rtype: str or unicode
        """
        pass

Sys.path is also setup correctly, as it throws now error when making

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

If it is relevant i also include the setup.py:

from setuptools import setup

setup(name='My Module',
      version='0.1',
      description='Internet of Things',
      url='https://example.com',
      author='Master Yoda',
      author_email='yoda@example.com',
      license='GPLv3',
      packages=['mymodule'],
      zip_safe=False)

What can i change to make autodoc work?

lalu
  • 331
  • 1
  • 3
  • 10
  • I don't understand how `.. automodule:: mymodule` can work. You don't have a module with that name. I would expect `.. automodule:: myproject.main` to work. – mzjn Mar 08 '19 at 12:55
  • @mzjn you were right! I had to write "automodule:: myproject.main" to make it work. Thank you so much. Do you want to answer this question? :) – lalu Mar 08 '19 at 12:57
  • I accidentially wrote `mymodule` instead of `myproject` in my question, but this was not the reason why it did not work in the original code. However i mixed up module and package and wrote `myproject` instead of `myproject.main`. – lalu Mar 08 '19 at 13:04

2 Answers2

8

If your class is imported into __init__.py you may also need :imported-members: like so:

.. automodule:: myproject
   :imported-members:
   :members:
   :undoc-members:
   :show-inheritance:
spacether
  • 2,136
  • 1
  • 21
  • 28
6

The main module is in the myproject package. In order to document main, you need the following:

.. automodule:: myproject.main
   :members:
mzjn
  • 48,958
  • 13
  • 128
  • 248