I have reviewed the sphinx documentation to generate the python documentation. When I generate the documentation in html format using the .rst files that do not reference any python source code, the documentation is generated correctly.
In my configuration I work with the following files: conf.py, index.rst, tutorial.rst, project.rst and pkg_app.rst
I attach the content of each of them:
conf.py:
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'hmed'
copyright = '2023, Ramiro Jativa'
author = 'Ramiro Jativa'
release = '1.0.41'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = ['sphinx.ext.autodoc']
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'alabaster'
html_static_path = ['_static']
index.rst:
.. hmed documentation master file, created by
sphinx-quickstart on Thu Apr 27 17:53:25 2023.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to hmed's documentation!
================================
Requirements for production:
MySQL
Python
Flask
PyPi Libraries
Requirements for development:
sqlite3
Python
Flask
PyPi Libraries
Project structure:
project_name/pkg_app (include the source code distributed in various modules. And includes the __init__.py file)
project_name/sphinx_documentation (is the folder where the sphinx documentation is generated)
.. toctree::
:maxdepth: 2
:caption: Contents:
tutorial
project
pkg_app
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
tutorial.rst:
Tutorial
========
Modules
-------
Module 1: Tutorial for module 1.
This is the content for tutorial 1.
Module 2: Tutorial for module 2.
This is the content for tutorial 2.
project.rst:
Project Documentation
=====================
Achieved goals
--------------
Goal 1: This is the description of goal 1.
This is the detail of what was done to achieve goal 1.
Goal 2: This is the description of goal 2.
This is the detail of what was done to achieve goal 2.
Learned lessons
---------------
This paragraph describes what was learned in the project.
pkg_app.rst:
Source code documentation
=========================
The pkg_app folder includes the __init__.py, models.py, forms.py, and routes.py files
Using the indicated configuration, I proceed to execute the make html command and the documentation is generated by sphinx correctly.
Next I include the log of the execution of the make html command:
(venv_hmed) $ make clean
Removing everything under '_build'...
(venv_hmed) $ make html
Running Sphinx v5.3.0
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 4 source files that are out of date
updating environment: [new config] 4 added, 0 changed, 0 removed
reading sources... [100%] tutorial
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] tutorial
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.
The HTML pages are in _build/html.
As a result, the documentation is obtained in html format as indicated below:
Up to this point everything works correctly.
To generate the documentation of the files with the .py extension that are inside the pkg_app directory structure, I modify the content of the pkg_app.rst file with the following content:
pkg_app.rst:
Source code documentation
=========================
The pkg_app folder includes the __init__.py, models.py, forms.py, and routes.py files
Module contents
---------------
.. automodule:: pkg_app
:members:
:undoc-members:
:show-inheritance:
When the make html command is entered to generate the documentation in sphinx, the following warning message is displayed:
(venv_hmed) $ make clean
Removing everything under '_build'...
(venv_hmed) $ make html
Running Sphinx v5.3.0
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 4 source files that are out of date
updating environment: [new config] 4 added, 0 changed, 0 removed
reading sources... [100%] tutorial
WARNING: autodoc: failed to import module 'pkg_app'; the following exception was raised:
No module named 'pkg_app'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] tutorial
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.
The HTML pages are in _build/html.
QUESTION:
what is the correct configuration of the pkg_app.rst file so that it can generate the python documentation of all the modules inside the pkg_app package?
Thanks.
