Skip to content

opencord/voltha-docs

Folders and files

NameName
Last commit message
Last commit date

Latest commit

3e4d6d6 · Sep 17, 2024
Jan 23, 2023
Jan 23, 2023
Feb 23, 2023
Sep 17, 2024
May 6, 2024
Dec 29, 2022
May 6, 2024
May 6, 2024
Sep 17, 2024
Sep 17, 2024
Sep 14, 2023
Sep 17, 2024
Sep 17, 2024
Sep 17, 2024
Sep 17, 2024
Sep 11, 2023
May 6, 2024
Nov 14, 2019
May 6, 2024
Dec 11, 2019
Jun 28, 2024
Sep 17, 2024
Apr 30, 2024
Apr 8, 2020
Jan 5, 2022
Dec 20, 2023
Feb 23, 2023
Sep 14, 2021
Apr 18, 2024

Repository files navigation

Documentation Guide

Writing Documentation

Docs are generated using Sphinx.

Documentation can be written in reStructuredText (.rst) or Markdown (.md), but reStructuredText is preferred as that filetype supports features like embedded diagrams and tables.

In reStructuredText documents, to create the section hierarchy (mapped in HTML to <h1> through <h5>) use these characters to underline headings in the order given: =, - ", ', ^.

Building the Docs

The documentation build process is stored in the Makefile. Building docs requires Python to be installed, and most steps will create a virtualenv (venv_docs) which contains the required tools. You may also need to install the enchant C library using your system's package manager for the spelling checker to function properly.

Run make html to generate html documentation in _build/html.

To check the formatting of documentation, run make lint. This will be done in Jenkins to validate the documentation, so please do this before you create a patchset.

To check spelling, run make spelling. If there are additional words that are correctly spelled but not in the dictionary (acronyms, trademarks, etc.) please add them to the dict.txt file.

Creating new Versions of Docs

To change the version shown on the built site, change the contents of the VERSION file.

There is a make multiversion target which will build all versions published on the remote to _build. This will use a fork of sphinx-multiversion to build multiple versions for the site.

Creating Graphs and Diagrams

Multiple tools are available to render inline text-based graphs definitions and diagrams within the documentation. This is preferred over images as it's easier to change and see changes over time as a diff.

Graphviz supports many standard graph types.