[feature] Added prototype for generating comprehensive docs openwisp#107

Closes openwisp#107

.gitignore

@@ -2,3 +2,4 @@
 _build/
 
 .vscode/
+modules/

_templates/layout.html

@@ -1,6 +1,7 @@
 {% extends "!layout.html" %}
 {% block footer %}
 {{ super() }}
+<h1> Version </h1>
 <script async src="https://www.googletagmanager.com/gtag/js?id=G-RGGYQ3GC31"></script>
 <script>
     window.dataLayer = window.dataLayer || [];

_templates/versions.html

@@ -0,0 +1,52 @@
+<style>
+  .rst-versions.shift-up {
+    background: #ddd;
+  }
+
+  span.rst-current-version {
+    background: #fff !important;
+    color: #df5d43 !important;
+  }
+
+  .rst-other-versions dt {
+    font-weight: bold !important;
+  }
+
+  .rst-versions .rst-other-versions dd a {
+    color: #777;
+  }
+
+  .rst-versions .rst-other-versions dd a:hover,
+  .rst-versions .rst-other-versions dd.selected a {
+    color: #df5d43 !important;
+  }
+</style>
+
+
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    Version: {{ current_ow_version }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    <dl>
+      <dt>{{ _('Versions') }}</dt>
+      {% for ow_version, ow_version_root_url in ow_versions %}
+      <dd class="{% if ow_version == current_ow_version %}selected{% endif %}">
+        <a href="{{ ow_version_root_url }}/{{ pagename }}.html">{{ ow_version }}</a>
+      </dd>
+      {% endfor %}
+    </dl>
+    <dl>
+      <dt>{{ _('Versions') }}</dt>
+      <dd><a href="//openwisp-radius.readthedocs.io/_/downloads/en/stable/pdf/">PDF</a></dd>
+
+      <dd><a href="//openwisp-radius.readthedocs.io/_/downloads/en/stable/htmlzip/">HTML</a></dd>
+
+      <dd><a href="//openwisp-radius.readthedocs.io/_/downloads/en/stable/epub/">Epub</a></dd>
+
+    </dl>
+    <br>
+    </dl>
+  </div>
+</div>

conf.py

@@ -31,11 +31,14 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'rst2pdf.pdfbuilder',
+    'sphinxcontrib.jquery',
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
     'sphinx.ext.githubpages',
     'notfound.extension',
+    'sphinx_multiversion',
     'openwisp.sphinx.theme',
 ]
 
@@ -181,7 +184,11 @@
 
 # Custom sidebar templates, maps document names to template names.
 #
-# html_sidebars = {}
+html_sidebars = {
+    '**': [
+        'versions.html',
+    ],
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -428,10 +435,6 @@
 #
 # epub_use_index = True
 
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
-
 notfound_urls_prefix = '/docs/'
 notfound_context = {
     'title': 'Page not found',
@@ -440,3 +443,24 @@
         'perform a search for what you were looking for.'
     ),
 }
+
+
+smv_remote_whitelist = None
+smv_branch_whitelist = 'master'
+smv_tag_whitelist = r'^.*$'
+
+# Configuration for generating comprehensive docs
+import yaml
+import os
+
+with open('config.yml', 'r') as f:
+    ow_docs_config = yaml.safe_load(f)
+
+html_context = {
+    'current_ow_version': os.environ.get('OPENWISP2_VERSION', 'stable'),
+    'ow_versions': []
+}
+
+for ow_version in ow_docs_config['versions']:
+    ow_version_name = ow_version['name']
+    html_context['ow_versions'].append([ow_version_name, f'/{ow_version_name}'])

config.yml

@@ -0,0 +1,15 @@
+---
+
+versions:
+  - name: latest
+    modules:
+      - name: openwisp-firmware-upgrader
+        branch: reorder-docs
+      - name: openwisp-controller
+        branch: reorder-docs
+  - name: stable
+    modules:
+      - name: openwisp-firmware-upgrader
+        branch: reorder-docs-stable
+      - name: openwisp-controller
+        branch: reorder-docs-stable

index.rst

@@ -6,29 +6,17 @@ OpenWISP Documentation
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :glob:
 
    user/quickstart
-   user/configure-device
-   user/monitoring
-   user/templates
-   user/configuration-variables
-   user/vpn
-   user/wireguard
-   user/zerotier
-   user/configure-push-updates
-   user/send-commands
-   user/subnet-division-rules
-   user/firmware-upgrades
+   modules/*/docs/*
    user/network-topology
    user/radius
    user/wifi-login-pages
    user/django-settings
    user/usage-metric-collection
    tutorials/demo
-   tutorials/wifi-access-point.rst
-   tutorials/hotspot
-   tutorials/mesh
    general/architecture
    general/values
    general/help-us

pulling_modules.py

@@ -0,0 +1,59 @@
+import os
+import subprocess
+
+import yaml
+
+
+def clone_or_update_repo(module_name, branch):
+    repo_url = f'git@github.com:openwisp/{module_name}.git'
+    repo_path = f'modules/{module_name}'
+
+    if os.path.exists(repo_path):
+        print(f"Repository '{module_name}' already exists. Updating...")
+        subprocess.run(['git', 'remote', 'set-branches', 'origin', branch], cwd=repo_path, check=True)
+        subprocess.run(['git', 'fetch', '--update-shallow', 'origin', branch], cwd=repo_path, check=True)
+        subprocess.run(['git', 'checkout', branch], cwd=repo_path, check=True)
+    else:
+        print(f"Cloning repository '{module_name}'...")
+        subprocess.run(
+            [
+                'git',
+                'clone',
+                # '--single-branch',
+                '--branch',
+                branch,
+                '--depth',
+                '1',
+                repo_url,
+                repo_path,
+            ],
+            check=True,
+        )
+        subprocess.run(
+            ['git', 'sparse-checkout', 'init', '--cone'], cwd=repo_path, check=True
+        )
+        subprocess.run(
+            ['git', 'sparse-checkout', 'set', 'docs'], cwd=repo_path, check=True
+        )
+
+
+def main():
+    with open('config.yml') as f:
+        config = yaml.safe_load(f)
+
+    for version in config['versions']:
+        for module in version['modules']:
+            module_name = module['name']
+            branch = module['branch']
+            clone_or_update_repo(module_name, branch)
+        version_name = version['name']
+
+        os.makedirs(f'_build/{version_name}', exist_ok=True)
+        os.environ['OPENWISP2_VERSION'] = version_name
+        subprocess.run(
+            ['sphinx-build', '-b', 'html', '.', f'_build/{version_name}'], check=True
+        )
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -1,6 +1,9 @@
 # Sphinx temporarily pinned because of this issue
 # https://github.com/sphinx-doc/sphinx/issues/11633
 sphinx~=7.1.2
+svglib
+rst2pdf
+sphinxcontrib
 sphinx-notfound-page
 openwisp-sphinx-theme~=1.0.0
 openwisp-utils[qa] @ https://github.com/openwisp/openwisp-utils/tarball/master