We can publish this on GC in the __new__ subdirectory.

Please rebase on the latest master and see my comments below.

I am happy of the progress we are making here! 👏 🔥 🚀

Here's the summary of the improvements we have discussed.

Stable alias

We need to generate a symbolic link "stable", pointing to the latest available stable version.

We can generate it only if the following conditions are true:

• The link doesn't exist
• Or it exists and point to a different version that what we have computed to be the latest.

To compute the latest version, instead of having to specify it manually, let's determine that automatically.
The stable version is the highest non dev version, we can compute it by getting all available versions, and getting the higher value (eg: use max(version_list)).

YAML: avoid repeating modules

Let's avoid having to repeat the available modules in each version, eg:

---

modules:
  - name: openwisp-controller
    dir_name: controller
  - name: openwisp-monitoring
    dir_name: monitoring
  - name: openwisp-firmware-upgrader
    dir_name: firwmare-upgrader
  - name: openwisp-notifications
    dir_name: notifications
  - name: openwisp-network-topology
    dir_name: network-topology
  - name: openwisp-users
    dir_name: users
  - name: openwisp-utils
    dir_name: utils
versions:
  # just for example purposes
  # you can see the branch is missing
  # because it's implicit, we don't need to specify it
  - name: "24.06"
  - name: "22.05"
  - name: dev
    branch: reorder-docs

Menu is shown twice

The menu is shown twice, we need to have 1 menu only.

Separate current 22.05 docs from dev

We need to use the 22.05 branch for stable docs, so that we can do any change we need in the master branch without creating conflicts or missing pages with the old stable docs.

Simplify URL structure

With the current structure we would end up with an URL like the following:

https://openwisp.io/docs/stable/modules/openwisp-controller/docs/user/templates.html.

The goal is to get more friendly URLs like:

https://openwisp.io/docs/stable/controller/user/templates.html.

Here's a possible solution I thought, which as a bonus also allows to avoid building files like README.rst, CONTRIBUTING.rst, CHANGES.rst which we should not build.

Every time we clone/checkout, we copy or link the docs/ directory to the root of the docs repository, renaminig it to the value of the dir_name attribute in the YAML.

We have to instruct sphinx to not build anything in the modules directory, the following seems to work for me:

diff --git a/conf.py b/conf.py
index e711b80..dd19d8c 100644
--- a/conf.py
+++ b/conf.py
@@ -85,7 +85,7 @@ language = 'en'
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['README.rst', '_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['README.rst', '_build', 'Thumbs.db', '.DS_Store', 'modules/*']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

Once the build step is completed, we can remove the copies/link.

We need to add those dirs in the .gitignore so we won't commit anything by mistake.

Allow building only a specific version

The previous step will make building only a specific version harder, due to the copying/linking renaming and deleting of the docs directory each time.

Can you add an option to allow do that through the Makefile?

Include more modules

Include the following repos:

• IPAM
• openwisp-config (let's use openwrt-config-agent as dir_name)
• openwrt-openwisp-monitoring (let's use openwrt-monitoring-agent as dir_name)
• wifi-login-pages
• ansible-openwisp2
• docker-openwisp

While reviewing and improving the docs of OpenWISP Controller, I found quite a lot of broken links.
Our build here is supposed to be able to detect broken links, but I think the changes of this PR are making the run-qa-checks script ineffective, so please double check that, ensure that broken links are detected.

Another thing we will need to verify is that PDF opens correctly.
A few days ago I couldn't open the generated PDF, now the error went away.
However, it's better to have an automatic verification mechanism.