From 433ea4d0ded6018c81bc210d1a73206a3c85ee28 Mon Sep 17 00:00:00 2001
From: Oliver <oliver.henry.walters@gmail.com>
Date: Thu, 25 May 2023 22:42:16 +1000
Subject: [PATCH] Documentation Improvements (#4894)

* Improvements for version banner

- Display at the bottom of the page
- Simplify text

* Use mkdocs version provider

* use 'navigation.instant'

* Support modern mkdocs features

- Much better navigation and improved features

* Content changes

* Add code to find previous versions

* Remove modern python syntax

* display output codes

* Hide version banner

* Extra debug message

* update terminology.md
---
 docs/.gitignore                               |   1 +
 docs/_includes/overrides/main.html            |   6 +-
 .../overrides/partials/version_banner.html    |   6 +-
 docs/docs/extend/how_to_plugin.md             |   5 +-
 docs/docs/extend/plugins.md                   |  30 ++--
 docs/docs/hooks.py                            | 136 ++++++++++++++----
 docs/docs/terminology.md                      |   8 ++
 docs/mkdocs.yml                               |  19 +++
 8 files changed, 164 insertions(+), 47 deletions(-)

diff --git a/docs/.gitignore b/docs/.gitignore
index 2f10cb1dc7..ecbeb1b0ab 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -12,5 +12,6 @@ site/
 
 # Temp files
 releases.json
+versions.json
 
 .vscode/
diff --git a/docs/_includes/overrides/main.html b/docs/_includes/overrides/main.html
index e6bcd5b914..576314115d 100644
--- a/docs/_includes/overrides/main.html
+++ b/docs/_includes/overrides/main.html
@@ -1,6 +1,6 @@
 {% extends "base.html" %}
 
-{% block header %}
+{% block footer %}
 {% include "partials/version_banner.html" %}
-{% include "partials/header.html" %}
-{% endblock header %}
+{% include "partials/footer.html" %}
+{% endblock footer %}
diff --git a/docs/_includes/overrides/partials/version_banner.html b/docs/_includes/overrides/partials/version_banner.html
index 017e285153..0db2535c16 100644
--- a/docs/_includes/overrides/partials/version_banner.html
+++ b/docs/_includes/overrides/partials/version_banner.html
@@ -1,13 +1,13 @@
-{% if config.version_banner %}
+{% if False and config.version_banner %}
 <div class='alert alert-warning alert-dismissable alert-version' role='alert'>
     <div class='md-grid md-typeset'>
         <small>
         {% if config.readthedocs.version == 'latest' %}
-            This documentation is for the <em>development</em> version of InvenTree, which may be significantly different from the stable releases.
+            This documentation is for the <strong>development</strong> version of InvenTree.
         {% else %}
             This documentation is for an outdated version of InvenTree.
         {% endif %}
-        For <em>stable</em> release documentation, use the version selector located in the bottom right corner of this page.
+        For <strong>stable</strong> release documentation, use the version selector located in the bottom right corner of this page.
         </small>
         <button type="button" class="close" data-dismiss="alert" aria-label="Close"><span aria-hidden="true">&times;</span></button>
     </div>
diff --git a/docs/docs/extend/how_to_plugin.md b/docs/docs/extend/how_to_plugin.md
index 41a9b224c4..e7b5c019df 100644
--- a/docs/docs/extend/how_to_plugin.md
+++ b/docs/docs/extend/how_to_plugin.md
@@ -1,8 +1,9 @@
 ---
-title: How to plugin
+title: Developing Plugins
 ---
 
-## How to write a plugin
+## How to Develop a Plugin
+
 A short introductory guide for plugin beginners.
 
 ### Should it be a plugin?
diff --git a/docs/docs/extend/plugins.md b/docs/docs/extend/plugins.md
index 7cb8d439e0..caa67a70a4 100644
--- a/docs/docs/extend/plugins.md
+++ b/docs/docs/extend/plugins.md
@@ -89,17 +89,19 @@ Common use cases are covered by pre-supplied modules in the form of *mixins* (si
 
 Supported mixin classes are:
 
-- [ActionMixin](./plugins/action.md)
-- [APICallMixin](./plugins/api.md)
-- [AppMixin](./plugins/app.md)
-- [BarcodeMixin](./plugins/barcode.md)
-- [EventMixin](./plugins/event.md)
-- [LabelPrintingMixin](./plugins/label.md)
-- [LocateMixin](./plugins/locate.md)
-- [NavigationMixin](./plugins/navigation.md)
-- [PanelMixin](./plugins/panel.md)
-- [ReportMixin](./plugins/report.md)
-- [ScheduleMixin](./plugins/schedule.md)
-- [SettingsMixin](./plugins/settings.md)
-- [UrlsMixin](./plugins/urls.md)
-- [ValidationMixin](./plugins/validation.md)
+| Mixin | Description |
+| --- | --- |
+| [ActionMixin](./plugins/action.md) | Run custom actions |
+| [APICallMixin](./plugins/api.md) | Perform calls to external APIs |
+| [AppMixin](./plugins/app.md) | Integrate additional database tables |
+| [BarcodeMixin](./plugins/barcode.md) | Support custom barcode actions |
+| [EventMixin](./plugins/event.md) | Respond to events |
+| [LabelPrintingMixin](./plugins/label.md) | Custom label printing support |
+| [LocateMixin](./plugins/locate.md) | Locate and identify stock items |
+| [NavigationMixin](./plugins/navigation.md) | Add custom pages to the web interface |
+| [PanelMixin](./plugins/panel.md) | Add custom panels to web views |
+| [ReportMixin](./plugins/report.md) | Add custom context data to reports |
+| [ScheduleMixin](./plugins/schedule.md) | Schedule periodic tasks |
+| [SettingsMixin](./plugins/settings.md) | Integrate user configurable settings |
+| [UrlsMixin](./plugins/urls.md) | Respond to custom URL endpoints |
+| [ValidationMixin](./plugins/validation.md) | Provide custom validation of database models |
diff --git a/docs/docs/hooks.py b/docs/docs/hooks.py
index 1b6ba43bfb..756b8aa556 100644
--- a/docs/docs/hooks.py
+++ b/docs/docs/hooks.py
@@ -4,7 +4,88 @@ import json
 import os
 import re
 from datetime import datetime
-from urllib import request
+from distutils.version import StrictVersion
+
+import requests
+
+
+def fetch_rtd_versions():
+    """Get a list of RTD docs versions to build the version selector"""
+
+    print("Fetching documentation versions from ReadTheDocs")
+
+    versions = []
+
+    def make_request(url, headers):
+        """Make a single request to the RTD API"""
+        response = requests.get(url, headers=headers)
+
+        if response.status_code != 200:
+            print(f"Error fetching RTD versions: {response.status_code}")
+            return
+
+        data = json.loads(response.text)
+
+        for entry in data['results']:
+            slug = entry['slug']
+            ref = entry['ref']
+            url = entry['urls']['documentation']
+            aliases = []
+
+            if ref is not None:
+                aliases.append(slug)
+
+            version = ref or slug
+
+            if version == 'latest':
+                continue
+
+            versions.append({
+                'version': version,
+                'title': version,
+                'aliases': aliases,
+            })
+
+        if data['next']:
+            make_request(data['next'], headers)
+
+    # Fetch the list of versions from the RTD API
+    token = os.environ.get('RTD_TOKEN', None)
+    if token:
+        headers = {'Authorization': f'Token {token}'}
+        url = "https://readthedocs.org/api/v3/projects/inventree/versions/?active=true&limit=50"
+        make_request(url, headers)
+    else:
+        print("No RTD token found - skipping RTD version fetch")
+
+    # Sort versions by version number
+    versions = sorted(versions, key=lambda x: StrictVersion(x['version']), reverse=True)
+
+    # Add "latest" version first
+    if not any((x['title'] == 'latest' for x in versions)):
+        versions.insert(0, {
+            'title': 'Development',
+            'version': 'latest',
+            'aliases': ['main', 'latest', 'development',],
+        })
+
+    # Ensure we have the 'latest' version
+    current_version = os.environ.get('READTHEDOCS_VERSION', None)
+
+    if current_version and not any((x['title'] == current_version for x in versions)):
+        versions.append({
+            'version': current_version,
+            'title': current_version,
+            'aliases': [],
+        })
+
+    output_filename = os.path.join(os.path.dirname(__file__), 'versions.json')
+
+    print("Discovered the following versions:")
+    print(versions)
+
+    with open(output_filename, 'w') as fo:
+        json.dump(versions, fo, indent=2)
 
 
 def get_release_data():
@@ -23,37 +104,35 @@ def get_release_data():
 
         print("Loading release information from 'releases.json'")
         with open(json_file) as f:
-            releases = json.loads(f.read())
-    else:
-        # Download release information via the GitHub API
-        print("Fetching InvenTree release information from api.github.com:")
-        releases = []
+            return json.loads(f.read())
 
-        # Keep making API requests until we run out of results
-        page = 1
+    # Download release information via the GitHub API
+    print("Fetching InvenTree release information from api.github.com:")
+    releases = []
 
-        while 1:
-            url = f"https://api.github.com/repos/inventree/inventree/releases?page={page}&per_page=150"
+    # Keep making API requests until we run out of results
+    page = 1
 
-            print(f" - {url}")
+    while 1:
+        url = f"https://api.github.com/repos/inventree/inventree/releases?page={page}&per_page=150"
 
-            response = request.urlopen(url, timeout=30)
-            assert response.status == 200
+        response = requests.get(url, timeout=30)
+        assert response.status_code == 200
 
-            data = json.loads(response.read().decode())
+        data = json.loads(response.text)
 
-            if len(data) == 0:
-                break
+        if len(data) == 0:
+            break
 
-            for item in data:
-                releases.append(item)
+        for item in data:
+            releases.append(item)
 
-            page += 1
+        page += 1
 
-        # Cache these results to file
-        with open(json_file, 'w') as f:
-            print("Saving release information to 'releases.json'")
-            f.write(json.dumps(releases))
+    # Cache these results to file
+    with open(json_file, 'w') as f:
+        print("Saving release information to 'releases.json'")
+        f.write(json.dumps(releases))
 
     return releases
 
@@ -77,11 +156,18 @@ def on_config(config, *args, **kwargs):
 
     rtd = os.environ.get('READTHEDOCS', False)
 
+    # Check for 'versions.json' file
+    # If it does not exist, we need to fetch it from the RTD API
+    if os.path.exists(os.path.join(os.path.dirname(__file__), 'versions.json')):
+        print("Found 'versions.json' file")
+    else:
+        fetch_rtd_versions()
+
     if rtd:
         rtd_version = os.environ['READTHEDOCS_VERSION']
         rtd_language = os.environ['READTHEDOCS_LANGUAGE']
 
-        site_url = f"https://inventree.readthedocs.io/{rtd_language}/{rtd_version}"
+        site_url = f"https://docs.inventree.org/{rtd_language}/{rtd_version}"
         assets_dir = f"/{rtd_language}/{rtd_version}/assets"
 
         print("Building within READTHEDOCS environment!")
@@ -131,7 +217,7 @@ def on_config(config, *args, **kwargs):
         tag = item['tag_name']
 
         # Check that the tag is formatted correctly
-        re.match('^\d+\.\d+\.\d+$', tag)
+        re.match(r'^\d+\.\d+\.\d+$', tag)
 
         if not re.match:
             print(f"Found badly formatted release: {tag}")
diff --git a/docs/docs/terminology.md b/docs/docs/terminology.md
index 8e5c68d107..ba127d9a48 100644
--- a/docs/docs/terminology.md
+++ b/docs/docs/terminology.md
@@ -17,6 +17,10 @@ PLM can also mean product lifecycle management – those systems manage all stag
 
 A similar system is [Partkeepr](https://partkeepr.org/) (seems mostly inactive - there is a 3rd party importer).
 
+### Material Resource Planning *(MRP)*
+
+Material Requirements Planning software, is designed to assist businesses in effectively managing their manufacturing processes. It helps with the planning and control of inventory, production schedules, and procurement activities. MRP software utilizes various algorithms and data inputs, such as sales forecasts, production capacity, and bill of materials, to generate material requirements plans, schedule production orders, and optimize inventory levels.
+
 ### Asset Management *(AM)*
 Manages many unique items, which need tracking per part and are assignable to users / groups / locations. These systems often include features like item states, refurbishing / maintenance / reservation, or request-flows.
 Often these systems are used for IT-Hardware (then they are called *ITAM*).
@@ -30,3 +34,7 @@ Popular, fully fledged ERPs are [ERPNext](https://erpnext.com/) or [odoo](https:
 ### Customer Relationship Manager *(CRM)*
 
 Customer relationship management (CRM) is a technology for managing all your company's relationships and interactions with customers and potential customers.
+
+### Manufacturing Execution System *(MES)*
+
+A Manufacturing Execution System (MES), oversees, monitors, records, and manages the entire manufacturing process from raw materials to finalized products.
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 28b7db4388..6d4bed838f 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -11,16 +11,20 @@ repo_name: inventree/inventree
 # Theme
 theme:
   name: material
+  font:
+    text: Roboto
   custom_dir: _includes/overrides
   palette:
     - media: "(prefers-color-scheme: light)"
       scheme: default
+      primary: blue
       accent: light blue
       toggle:
         icon: material/toggle-switch
         name: Switch to dark mode
     - media: "(prefers-color-scheme: dark)"
       scheme: slate
+      primary: blue
       accent: light blue
       toggle:
         icon: material/toggle-switch-off-outline
@@ -30,8 +34,19 @@ theme:
   icon:
     repo: fontawesome/brands/github
   features:
+    - header.autohide
+    - navigation.expand
+    - navigation.footer
+    - navigation.indexes
+    - navigation.instant
+    # - navigation.sections
+    - navigation.tracking
     - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.top
+    - search.highlight
     - toc.autohide
+    - toc.follow
 edit_uri: "" # Disable "Edit" button
 extra_css:
   - stylesheets/brands.css
@@ -225,6 +240,10 @@ extra:
   #  provider: google
   #  property: UA-143467500-1
 
+  version:
+    default: stable
+    provider: mike
+
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/inventree/inventree