This repository contains the main source of the Unified Documentation of OpenWISP, published at openwisp.io/docs.
It implements logic which pulls source documents from different OpenWISP modules in order to build a single unified documentation website.
Requirements: Python >= 3.9.
- Fork this repository
- Clone this repository using the following command:
git clone https://github.com/<your-username>/openwisp2-docs.git
- Install sphinx on your local machine using:
pip install -r requirements.txt
- You can build the documentation using the following command
# This command will generate the documentation in all formats - HTML, PDF and ePUB
make build
# The ``formats`` argument is a comma separated list of formats to build,
# e.g. ``formats=html,pdf,epub``. The default is to build all available
# formats, which currently are ``html``, ``pdf`` and ``epub``.
make build formats=pdf,html
# This command is a shortcut for generating only HTML documentation during
# development, since building PDF and ePUB takes time. It also supports
# the VERSION argument.
make build_html
- Open the generated HTML files in your browser.
By default, the make build
command will generate documentation in all
supported output formats: HTML, PDF, and ePUB.
If you want to generate the documentation in specific formats, you can
specify the FORMATS
argument. The FORMATS
argument accepts a
comma-separated list of formats to generate. The supported formats are:
html
: HTML documentationpdf
: PDF documentationepub
: ePUB documentation
For example, to generate only HTML and PDF documentation, you can run:
make build FORMATS=html,pdf
To generate all supported formats, just omit the FORMATS
argument:
make build
# This command will only generate HTML
make build FORMATS=html
By default, the make build
command will generate documentation for all
the versions defined in config.yml
.
If you want to generate the documentation for a specific version, you can
do so by using the VERSION
argument. VERSION
accepts any version
that is specified in the config.yml
file.
For example, if you want to generate documentation for the dev
version, you can run:
make build VERSION=dev
This is useful if you only want to generate documentation for the version you are currently working on, or if you want to generate documentation for a specific version without having to rebuild all the other versions as well.
The make build
command is programmed to generate the documentation for
the modules that are defined in the config.yml
file. Sometimes, it may
be necessary to override the branch/remote of a module defined in the
config.yml
file to build the documentation for a specific version or
to test a specific commit/branch of a module.
You can do so by using the MODULES
argument. MODULES
accepts a
comma separated string where each item is of the following format:
version=<openwisp-version>,repository=<repo-owner>/<repo-name>,branch=<branch-name>
E.g. if you want to build the documentation for the dev
version, but
want to use the feature
branch of openwisp-controller of your fork,
then the command will be:
make build MODULES="version=dev:repository=<your-username>/openwisp-controller:branch=feature"
The MODULES
argument allows you to override the default settings for a
single module, or multiple modules, defined in the config.yml
file.
You can use the MODULES
argument to add modules to a version that is
not defined in the config.yml
file.
By default, the OpenWISP modules are cloned over HTTPS. This may pose a
hurdle if you wish to make changes to the cloned modules and push them to
the remote URL. To use SSH remotes, you can set the environment variable
SSH=1
. This will instruct the build to clone the modules using SSH
instead of HTTPS. For example:
SSH=1 make build
make spellcheck
- If any help regarding installing and using sphinx and reStructured Text is required then please visit this link.
- Feel free to post any doubt or comment through our support channels.