[docs] Added docstrfmt check to run-qa-checks

- Eliminated obsolete check_line_length.py script
- Reformatted docs and scripts

.github/workflows/ci.yml

@@ -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 attrs
 
       - name: Install test dependencies
         run: |

Makefile

@@ -261,3 +261,7 @@ dummy:
 .PHONY: version_map
 version_map:
 	$(SPHINXBUILD) -b version_map $(ALLSPHINXOPTS) $(BUILDDIR)/version_map
+
+.PHONY: format
+format:
+	docstrfmt --pyproject-config ./pyproject.toml .

README.rst

@@ -1,27 +1,25 @@
-======================
 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
 
-3. Install sphinx on your local machine using::
+3. Install sphinx on your local machine using:
 
 .. code-block:: shell
 
@@ -42,7 +40,8 @@ Requirements: Python >= 3.9.
     # the VERSION argument.
     make build_html
 
-.. note::
+..
+    note:
 
     Please refer the "`build options" <#build-options>`_section of this
     configuration for a complete reference of the available options.
@@ -55,13 +54,12 @@ Build options
 Building different formats
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-By default, the ``make build`` command will generate documentation in all
-supported output formats: HTML, PDF, and ePUB.
+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:
+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
@@ -87,64 +85,58 @@ To generate all supported formats, just omit the ``FORMATS`` argument:
 Building specific version
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-By default, the ``make build`` command will generate documentation for
-all the versions defined in ``config.yml``.
+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.
+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:
+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.
+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.
+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:
+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:
+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.
+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.
+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:
+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
 
@@ -153,9 +145,8 @@ using SSH instead of HTTPS. For example:
 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>`_.

conf.py

@@ -471,5 +471,3 @@
 epub_basename = f'OpenWISP-{version}'
 
 nitpicky = True
-
-

contents.rst

@@ -4,13 +4,13 @@ OpenWISP Documentation Contents
 ===============================
 
 .. toctree::
-   :maxdepth: 3
+    :maxdepth: 3
 
-   first-steps
-   project-overview
-   installers
-   modules
-   openwrt-agents
-   tutorials/index
-   community
-   developer/index
+    first-steps
+    project-overview
+    installers
+    modules
+    openwrt-agents
+    tutorials/index
+    community
+    developer/index

index.rst

@@ -10,8 +10,8 @@ OpenWISP Documentation
 
 .. note::
 
-    For a complete overview of this documentation,
-    refer to the :doc:`Full Table of Contents <contents>`.
+    For a complete overview of this documentation, refer to the :doc:`Full
+    Table of Contents <contents>`.
 
 .. important::
 

pyproject.toml

@@ -0,0 +1,3 @@
+[tool.docstrfmt]
+extend_exclude = ["*.py", "**/**/*.py"]
+line_length = 74

run-qa-checks

@@ -2,6 +2,8 @@
 
 set -e
 
+docstrfmt -c -v --pyproject-config ./pyproject.toml .
+
 # openwisp-utils checks
 #This is done first to ignore build directories for openwisp-utils checks
 openwisp-qa-check \
@@ -12,10 +14,8 @@ openwisp-qa-check \
     --skip-black \
     --skip-checkrst
 
-./check_line_length.py
-
 echo ''
-echo 'Checking documentation build status'
+echo 'Build documention to look for syntax errors'
 make build
 
 # check for broken link

version_switcher/__init__.py

@@ -1,7 +1,10 @@
 def setup(app):
     from .builders import VersionSwitcherIndexBuilder
-    from .event_callbacks import (html_builder_inited, set_version_context,
-                                  update_version_map)
+    from .event_callbacks import (
+        html_builder_inited,
+        set_version_context,
+        update_version_map,
+    )
 
     app.add_builder(VersionSwitcherIndexBuilder)
     app.connect('builder-inited', html_builder_inited)