CODEWITHSUNDEEP
pycharmpython-sphinx
llevar
llevar

Reputation: 785

Get Sphinx in Pycharm to include my docstrings in generated html

I have a Pycharm project running the 3.7.2 Python interpreter and I configured Sphinx for generating documentation. My project has the following structure:

/my_project/
  /docs/
  /src/
    /modules/
    /tools/

There are python modules both in modules and tools that have been documented with docstrings. I have configured Sphinx to generate documentation in /docs, but this documentation only has a basic index.rst. How can I get python module documentation from my docstrings to be populated into the /docs folder?

Upvotes: 4

Views: 1818

Answers (1)

Nathan
Nathan

Reputation: 8149

Maybe you could try the following:

  1. Ensure your modules which you're trying to document have an __init__.py file so you can import them as appropriate later on. In your case, your tools and modules directories need __init__.py files.
  2. Make sure all your modules which you're documenting have been set-up with proper sphinx annotations:

module_1.py:

"""
.. module:: module_1
   :platform: Unix, Windows
   :synopsis: A useful module indeed.
"""

def public_fn_with_sphinxy_docstring(name, state=None):
    """This function does something.

    :param name: The name to use.
    :type name: str.
    :param state: Current state to be in.
    :type state: bool.
    :returns:  int -- the return code.
    :raises: AttributeError, KeyError

    """
    return 0
  1. Create a new .rst file, maybe called code.rst, which includes the modules you wish to document. Then reference this new .rst file within your index.rst:

code.rst:

Documentation for the Code
**************************

.. automodule:: an_example_pypi_project


module #1 -- auto members
=========================

This is something I want to say that is not in the docstring.

.. automodule:: an_example_pypi_project.module_1
   :members:

index.rst:

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

   # other rst files you're including in your sphinx docs

   code.rst

Here is a really nice explanation and tutorial if you want to check this out as well. Hopefully that helps!

Upvotes: 3

Related Questions