[feature] Pull docs from OpenWISP modules to create a unified documentation Website #107

.github/dependabot.yml

@@ -0,0 +1,19 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "monthly"
+    commit-message:
+      prefix: "[deps] "
+  - package-ecosystem: "github-actions" # Check for GitHub Actions updates
+    directory: "/" # The root directory where the Ansible role is located
+    schedule:
+      interval: "monthly" # Check for updates weekly
+    commit-message:
+      prefix: "[ci] "

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ on:
 jobs:
   build:
     name: Python==3.10
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
 
     strategy:
       fail-fast: false
@@ -28,7 +28,7 @@ jobs:
           python-version: "3.10"
 
       - name: Upgrade python system packages
-        run: pip install -U pip wheel
+        run: pip install -U pip wheel setuptools
 
       - name: Install test dependencies
         run: |
@@ -39,24 +39,23 @@ jobs:
         run: sudo npm install -g stylelint
 
       - name: QA checks
-        run: ./run-qa-checks
+        run: PRODUCTION=1 ./run-qa-checks
 
-      - name: Google Cloud Auth
+      - name: Setup Google Cloud
         if: ${{ github.event_name=='push' }}
         uses: 'google-github-actions/auth@v2'
         with:
-          project_id: ${{ secrets.GCS_PROJECT_ID }}
           credentials_json: ${{ secrets.GCS_DOWNLOADS_SERVICE_ACCOUNT_JSON }}
-
-      - name: Google Cloud Setup
-        if: ${{ github.event_name=='push' }}
-        uses: google-github-actions/setup-gcloud@v2
-        with:
           project_id: ${{ secrets.GCS_PROJECT_ID }}
+          export_environment_variables: true
+
+      - name: 'Set up Cloud SDK'
+        uses: 'google-github-actions/setup-gcloud@v2'
 
       - name: Deploy pages to openwisp.io/docs
         if: ${{ github.event_name=='push' }}
-        run: gsutil -D  -m rsync -r ${{ env.SRC }} ${{ env.DEST }}
+        run: |
+          gsutil -m rsync -r ${{ env.SRC_URL }} ${{ env.DST_URL }}
         env:
-          SRC: /home/runner/work/openwisp-docs/openwisp-docs/_build/html
-          DEST: gs://${{ secrets.GCS_DOCS_BUCKET_NAME }}/docs
+          SRC_URL: /home/runner/work/openwisp-docs/openwisp-docs/_build/docs/
+          DST_URL: gs://${{ secrets.GCS_DOCS_BUCKET_NAME }}/docs/

.gitignore

@@ -2,3 +2,33 @@
 _build/
 
 .vscode/
+modules/*
+controller
+monitoring
+firmware-upgrader
+notifications
+network-topology
+users
+utils
+openwisp2-docs
+wifi-login-pages
+ipam
+openwrt-config-agent
+openwrt-monitoring-agent
+docker
+ansible
+versions_map.json
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+eggs/
+.eggs/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+

Makefile

@@ -3,20 +3,23 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build --fail-on-warning
+SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
+SRCDIR        = .
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -c . -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  build to build the documentation in all formats (PDF, HTML and ePUB)"
+	@echo "  build_html to build the documentation in HTML format only"
 	@echo "  html       to make standalone HTML files"
 	@echo "  dirhtml    to make HTML files named index.html in directories"
 	@echo "  singlehtml to make a single large HTML file"
@@ -48,11 +51,36 @@ help:
 clean:
 	rm -rf $(BUILDDIR)/*
 
+.PHONY: build
+build:
+	# If the build fails or is interrupted, the versions_map.json will
+	# stay in the root directory. This would cause bugs when re-creating
+	# the version map, so we remove it before building.
+	rm versions_map.json &> /dev/null || true
+
+	#If the build is successful, the version map is stored in the
+	# _build/ directory, allowing re-use of the version map when sphinx uses cache
+	# in subsequent builds and only builds the changed files.
+	mv _build/versions_map.json versions_map.json &> /dev/null || true
+
+	@echo "Building version map"
+	./build.py --formats version_map $(if $(VERSION),--version $(VERSION)) $(if $(MODULES),--modules $(MODULES))
+
+	@echo "Building documentation"
+	./build.py $(if $(FORMATS),--formats $(FORMATS)) $(if $(VERSION),--version $(VERSION)) $(if $(MODULES),--modules $(MODULES))
+
+	# Store the version map in the _build/ directory
+	mv versions_map.json _build/
+
+.PHONY: build_html
+build_html:
+	make build FORMATS=html $(ARGS)
+
 .PHONY: html
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) -W -b html $(ALLSPHINXOPTS) $(BUILDDIR)
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)"
 
 .PHONY: dirhtml
 dirhtml:
@@ -114,11 +142,17 @@ devhelp:
 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/NewcomersGuide"
 	@echo "# devhelp"
 
+.PHONY: pdf
+pdf:
+	$(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $(BUILDDIR)
+	@echo
+	@echo "Build finished. The pdf file is in $(BUILDDIR)."
+
 .PHONY: epub
 epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)
 	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+	@echo "Build finished. The epub file is in $(BUILDDIR)."
 
 .PHONY: epub3
 epub3:
@@ -223,3 +257,11 @@ dummy:
 	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
 	@echo
 	@echo "Build finished. Dummy builder generates no files."
+
+.PHONY: version_map
+version_map:
+	$(SPHINXBUILD) -Q -b version_map $(ALLSPHINXOPTS) $(BUILDDIR)/version_map
+
+.PHONY: format
+format:
+	docstrfmt -l 74 .

README.rst

@@ -1,40 +1,157 @@
-========================
-OpenWISP 2 Documentation
-========================
+OpenWISP Documentation
+======================
 
-This repository aims to help out **new users and contributors** to get
-start using and getting involved in `OpenWISP <http://openwisp.org>`_.
+This repository contains the main source of the Unified Documentation of
+OpenWISP, published at `openwisp.io/docs <https://openwisp.io/docs>`_.
 
-This repo at this stage is pretty much a work in progress, so
-contributions, feedback and suggestions are very welcome.
+It implements logic which pulls source documents from different OpenWISP
+modules in order to build a single unified documentation website.
 
 How to build the docs
 ---------------------
 
 Requirements: Python >= 3.9.
 
 1. Fork this repository
+2. Clone this repository using the following command:
 
-2. Clone this repository using the following command::
+.. code-block:: shell
 
-    git clone https://github.com/<your-username>/openwisp2-docs.git
+    git clone https://github.com/<your-username>/openwisp2-docs.git
 
-3. Install sphinx on your local machine using::
+3. Install sphinx on your local machine using:
+
+.. code-block:: shell
 
     pip install -r requirements.txt
 
-4. Build HTML::
+4. You can build the documentation using the following command
+
+.. code-block:: shell
+
+    # 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
 
-    make html
+..
+    note:
+
+    Please refer the "`build options" <#build-options>`_section of this
+    configuration for a complete reference of the available options.
 
 5. Open the generated HTML files in your browser.
 
+Build options
+-------------
+
+Building different formats
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 documentation
+- ``pdf``: PDF documentation
+- ``epub``: ePUB documentation
+
+For example, to generate only HTML and PDF documentation, you can run:
+
+.. code-block:: shell
+
+    make build FORMATS=html,pdf
+
+To generate all supported formats, just omit the ``FORMATS`` argument:
+
+.. code-block:: shell
+
+    make build
+
+.. code-block:: shell
+
+    # This command will only generate HTML
+    make build FORMATS=html
+
+Building specific version
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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:
+
+.. code-block:: shell
+
+    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.
+
+Overriding a module of a version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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:
+
+.. code-block:: text
+
+    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:
+
+.. code-block:: shell
+
+    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.
+
+Building with SSH remotes
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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:
+
+.. code-block:: shell
+
+    SSH=1 make build
+
 Need help?
 ----------
 
-- If any help regarding installing and using `sphinx` and
-  `reStructured Text` is required then please visit this
-  `link <http://www.sphinx-doc.org/en/stable/tutorial.html>`_.
-
+- If any help regarding installing and using `sphinx` and `reStructured
+  Text` is required then please visit this `link
+  <http://www.sphinx-doc.org/en/stable/tutorial.html>`_.
 - Feel free to post any doubt or comment through our `support channels
   <http://openwisp.org/support.html>`_.

_static/index.jinja2

@@ -0,0 +1,8 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta http-equiv="refresh" content="0; URL='{{ docs_root }}/{{ stable_version }}/index.html'" />
+</head>
+<body>
+</body>
+</html>

_styles/pdf-style.yml

@@ -0,0 +1,8 @@
+styles:
+  heading:
+    borderPadding:
+      - 5
+      - 0
+      - 5
+      - 10
+    spaceAfter: 16