4

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?

llevar
  • 755
  • 8
  • 24
  • 1
    See https://stackoverflow.com/a/25555982/407651 – mzjn Feb 19 '19 at 17:11
  • Thank you, but that doesn't say anything about Pycharm. Pycharm has Sphinx integration and from looking at the documentation it seems like it should be possible to generate everything using the Sphinx run configuration but I'm not really sure how. Thanks for that link though. – llevar Feb 19 '19 at 17:20
  • 1
    @llevar PyCharm does not have a run configuration for the steps in the link provided by @mzjn, specifically `sphinx-quickstart` to create a Sphinx project and `sphinx-apidoc` to generate reST stub files. It only has run configurations to generate output from reST files. You must use a terminal session. PyCharm does have a terminal. – Steve Piercy Feb 19 '19 at 19:41

1 Answers1

3

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!

Nathan
  • 7,853
  • 4
  • 27
  • 50
  • 1
    Thanks, after playing around with the automodule directives I got what I was looking for. – llevar Feb 20 '19 at 07:51