From d498a060503820be11a539419460bb0666253698 Mon Sep 17 00:00:00 2001 From: Daniel Baston Date: Tue, 20 Feb 2024 11:14:06 -0500 Subject: [PATCH] Doc: Add instructions for Python API documentation --- doc/source/development/dev_documentation.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/doc/source/development/dev_documentation.rst b/doc/source/development/dev_documentation.rst index 6946670ea065..e23d8965d7bf 100644 --- a/doc/source/development/dev_documentation.rst +++ b/doc/source/development/dev_documentation.rst @@ -30,6 +30,26 @@ Once installed, running ``sphinx-autobuild -b html source build`` from the ``doc and serve it on a local web server at ``http://127.0.0.1:8000``. The pages served will be automatically refreshed as changes are made to underlying ``rst`` documentation files. +Python API documentation +------------------------ + +Sphinx uses the `autodoc `_ extension +to generate documentation for the Python API from Python function docstrings. +To be correctly parsed by ``autodoc``, docstrings should follow the `numpydoc Style guide `_. +Docstrings may be found in two locations. If the function was defined in Python +(i.e., using a ``%pythoncode`` SWIG directive), then the docstring must be +placed within the function definition. If the function is defined in C++ only, +then the docstring should be placed in a separate file +containing only docstrings (located in :source_file:`swig/include/python/docs`). +Sphinx loads the Python bindings when generating documentation, so for it to see any changes +the following steps must be completed: + +- rebuild the Python bindings from the build directory (``cmake --build . --target python_binding``) +- make the updated Python bindings visible to Python, either by installing them, or by running ``scripts/setdevenv.sh`` + from the build directory +- update the timestamp of the ``rst`` files associated with the page where the documentation appears (e.g., ``touch doc/source/api/python/osgeo.ogr.rst``) + + .. _rst_style: Sphinx RST Style guide