How to automatically generate Python API documentation in PyCharm

Question

I have a Python project in PyCharm and I'd like to automatically generate API documentation (in the form of HTML) from my Python code and docstrings.

According to this page, there are a number of tools that generate Python API documentation:

• autosummary
• autodoc
• pdoc
• PyDoc
• pydoctor
• Doxygen

The page additionally notes that the following tools "process documentation":

• DocUtils
• Sphinx

The PyCharm documentation says that DocUtils and Sphinx can be used to "produce the formatted API documentation". However, this seems to be incorrect, as their configuration indicates that those tools process only *.rst files, not *.py files.

My question is this: Can I use the DocUtils or Sphinx features of PyCharm to generate the API documentation?

Failing that, can I use any features of PyCharm to do this?

Failing that, are there any tools to do this that integrate well with PyCharm?

Answer 1

I also stumbled on this problem in short:

My question is this: Can I use the DocUtils or Sphinx features of PyCharm to generate the API documentation?

No. However, you can use PyCharm to quickly view documentation ctrl+Q and it will be nicely formatted with links,tables etc.

Failing that, can I use any features of PyCharm to do this?

Not really, PyCharm can only insert documentation stub for functions and methods but it cannot do an api discovery to automatically comment everything it also cannot create rst documents stub.

Failing that, are there any tools to do this that integrate well with PyCharm?

Yes :) sphinx-apidoc it is a tool that will automatically create rst documents from your code. There is also less known autoapi

You just point to the root directory and voila it can even include members without doc string. It really just create a simple rst document using automodule syntax. After that you can just run sphinx task from PyCharm and you have a documentation of your code you can even use a theme like sphinx_rtd_theme to make it look really nice.

Example: sphinx-apidoc -o source/ ../ Assuming you created a doc folder inside you project, then cd doc and used sphinx-quickstart the above command goes up to parent directory to discover any source file and document them. The result is stored in <project>/doc/source folder. Among other files there will be a modules.rst pulling all auto generated files together.

Then in your index.rst you add a line in .. toctree:: ... source/modules

EDIT

Recently I found a new tool to which I quickly switched seeing how easy it is to use pdoc3