Documentation ============= It is assumed that `sphinx` is installed together with the required theme:: pip install sphinx .... pip install pydata-sphinx-theme Any other special requirements should also be installed prior to ``make``. Create a directory ``myproject``, from here call ``sphinx-quickstart docs`` from the desktop, this creates a subdirectory ``docs`` with the files conf.py, index.rst, make.bat, Makefile and subdirectories _static,_templates and either _build or build depending on your choice to the question of whether to build separate source and build directories. Directory structure ------------------- If using the default "Separate source and build directories (y/n) [n]:" Any changes to the body of the project run ``make html``, changes to conf.py _static files or templates require ``make clean`` then ``make html``:: docs ├─ conf.py ├─ index.rst ├─ _build ├─ _static ├─ _templates ├─ make.bat ├─ Makefile └─ body Sphinx Newer Structure ---------------------- Make directory with project name, from this location ``sphinx-quickstart docs``. When asked "Separate source and build directories?(y/n) [n]:" This will make a directory structure like this:: root ├──.readthedocs.yaml docs ├── build ├── make.bat ├── Makefile ├──requirements.txt └── source ├── conf.py ├── index.rst ├── _static └── _templates The advantage is that many changes can be updated simply by ``make html``. There are two configuration files, *requirements.txt* and *.readthedocs.yaml*. The first requirements.txt is for the local python program running sphinx. If features are present in *conf.py* which require an installation using *pip* then list out the names as shown in PyPi within *requirements.txt* (this assumes a virgin Python installation). *.readthedocs.yaml* must be in the root directory, in github this is where *README.md* is situated before any other configuration files are placed:: # Required version: 2 build: os: ubuntu-24.04 tools: python: "3.11" # Build documentation in the "docs/" directory with Sphinx sphinx: configuration: docs/source/conf.py # Optional but recommended, declare the Python requirements required python: install: - requirements: docs/requirements.txt *yaml* files are the modern equivalent of *yml* files, the contents are no different. Edit the ``conf.py`` file to show the path to the ``scripts`` directory. Add to the extensions sphinx.ext.autodoc, and sphinx.ext.napoleon, then within the body add the napoleon directives. Depending on your preference either activate google or numpy docstrings:: # uncomment the following, change path to where scripts is # path is relative to config.py import os import sys sys.path.insert(0, os.path.abspath('../../scripts/')) html_theme = "pydata_sphinx_theme" html_sidebars = { "contributing": ["sidebar-search-bs.html", "custom-template.html"], "changelog": [], } ## older version ''' html_sidebars = { '**': [ 'about.html', 'navigation.html', 'relations.html', # needs 'show_related': True theme option to display 'searchbox.html' ] ] ''' # add the dependancies within extensions for autodoc and napolean extensions =["sphinx.ext.autodoc", 'sphinx.ext.napoleon', "sphinx.ext.autosummary", #"numpydoc", # creates loads of warnings 'sphinx.ext.mathjax' ] # add napolean directives - using numpy style docstrings napoleon_google_docstring = False napoleon_numpy_docstring = True Autodoc is now setup to look in the directory scripts, which will contain all the python scripts which should include all the necessary docstrings. It is best to ensure that all variables, functions, methods and classes are correctly formatted according to PEP8 using pylint. If the directory has subdirectories add __init__.py. Set up the project with all the normal rst, example and image files, (include source.rst in the main index) then run a test with ``make html``. When in good shape start autogenerating the docstrings. Run ``~my_project\docs>sphinx-apidoc -o ./source ../scripts``. This creates two files scripts.rst and modules.rst in the source directory. ``modules.rst`` is the index for ``scripts.rst``, they can be used as they stand, but we will modify this. Check the main index.rst file, just before `Indices and Tables` heading we need a toctree pointing at `modules.rst`:: Sources ======= .. toctree:: :maxdepth: 3 source/modules Each python script will become our modules, so we require separate rst files for each of the modules within the source directory. Each module file will look a bit like part of the original `scripts.rst`:: Tree Class Module ================== tree\_class class ---------------------- .. automodule:: tree_class :members: :undoc-members: :show-inheritance: .. note:: In the heading escape any underscores. ``.. Automodule::`` is used to trigger autodocumenting and points towards tree_class.py located in the scripts directory. Make `scripts.rst` into the local index, by adding toctree from modules.rst which can now be deleted. The original scripts.rst had a ``Module contents``, which is no longer required. Within the scripts directory add any local import file required. If these are not part of the documentation do not include them as a module. ``make clean`` before re-running ``make html``. .. toctree:: :maxdepth: 4 notebook tree entry scale rgb-hsv rgb-yiq colour-tools Preparing for ReadTheDocs ------------------------- Older Layout ^^^^^^^^^^^^ In the root of the project place two files **gitignore** and **readthedocs.yml**, for the older style in the directory **docs** place **requirements.txt**, the two files **make.bat** and **Makefile** are also placed in docs. `readthedocs.yml` shows the versions required for sphinx and python, also the relative positions of conf.py and requirements.txt:: version: 2 sphinx: configuration: docs/conf.py python: version: 3 install: - requirements: docs/requirements.txt Newer Layout ^^^^^^^^^^^^ As with the older layout **gitignore** and **readthedocs.yml** are placed in the root. **requirements.txt** and the two files **make.bat** and **Makefile** are placed in the **docs** directory. Since **conf.py** is now placed in the source directory remember to change `readthedocs.yml`:: version: 2 sphinx: configuration: docs/source/conf.py python: version: 3 install: - requirements: docs/requirements.txt