From 2c51073a179ead66306957067c3a16c4cbc34b18 Mon Sep 17 00:00:00 2001
From: Karel van Klink <karel.vanklink@geant.org>
Date: Wed, 4 Oct 2023 17:11:08 +0200
Subject: [PATCH] convert glossary to rst, and open all external links in new
 page

---
 docs/source/apidocs/.gitignore |  1 -
 docs/source/conf.py            | 21 +++++++++--------
 docs/source/glossary.md        | 41 --------------------------------
 docs/source/glossary.rst       | 43 ++++++++++++++++++++++++++++++++++
 docs/source/static/custom.js   |  3 +++
 5 files changed, 57 insertions(+), 52 deletions(-)
 delete mode 100644 docs/source/apidocs/.gitignore
 delete mode 100644 docs/source/glossary.md
 create mode 100644 docs/source/glossary.rst
 create mode 100644 docs/source/static/custom.js

diff --git a/docs/source/apidocs/.gitignore b/docs/source/apidocs/.gitignore
deleted file mode 100644
index 72e8ffc0..00000000
--- a/docs/source/apidocs/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-*
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 2d75bf85..4b4687e1 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -1,21 +1,22 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(
+    os.path.join(
+        os.path.dirname(__file__),
+        '..', 'gso')))
+
+
 # -- Project information -----------------------------------------------------
 project = 'GÉANT Service Orchestrator'
 copyright = '2023, GÉANT Vereniging'
 author = 'GÉANT Orchestration and Automation Team'
 
 # -- General configuration ---------------------------------------------------
-extensions = ['sphinx_rtd_theme', 'myst_parser', 'sphinx.ext.autodoc']
+extensions = ['sphinx_rtd_theme', 'sphinx.ext.autodoc', 'sphinxcontrib.jquery']
 
 templates_path = ['templates']
 exclude_patterns = ['build', 'Thumbs.db', '.DS_Store', 'venv', 'vale', '__init__.py']
-source_suffix = {
-    '.md': 'markdown'
-}
-
-# -- Options for Markdown support --------------------------------------------
-myst_enable_extensions = ['attrs_block', 'deflist', 'replacements', 'smartquotes', 'strikethrough', 'fieldlist']
-suppress_warnings = ['myst.strikethrough']
-
 
 # -- Options for HTML output -------------------------------------------------
 html_theme = 'sphinx_rtd_theme'
@@ -24,11 +25,11 @@ html_theme_options = {
     'style_nav_header_background': 'rgb(0 63 95)',
 }
 html_css_files = ['custom.css']
+html_js_files = ['custom.js']
 html_logo = 'static/geant_logo_white.svg'
 
 # Both the class' and the __init__ method's docstring are concatenated and inserted.
 autoclass_content = 'both'
-# autodoc_typehints = 'none'
 
 # Display todos by setting to True
 todo_include_todos = True
diff --git a/docs/source/glossary.md b/docs/source/glossary.md
deleted file mode 100644
index 7035fa3b..00000000
--- a/docs/source/glossary.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# Glossary of terms
-
-{.glossary}
-BGP
-: Border Gateway Protocol: a path vector routing protocol described in 
-<a href="https://datatracker.ietf.org/doc/html/rfc4271" target="_blank">RFC 4271</a>.
-
-CNAME
-: A type of DNS record that is used as an alias from one hostname to another
-
-CRUD
-: Create, Read, Update, Delete
-
-FQDN
-: Fully Quantified Domain Name
-
-GSO
-: GÉANT Service Orchestrator
-
-IPAM
-: IP Address Management
-
-IS-IS
-: Intermediate System to Intermediate System: a routing protocol described in 
-<a href="https://datatracker.ietf.org/doc/html/rfc7142" target="_blank">RFC 7142</a>.
-
-ISO
-: International Organisation for Standardisation
-
-LSO
-: Lightweight Service Orchestrator
-
-NET
-: Network Entity Title: used for {term}`IS-IS` routing.
-
-SNMP
-: Simple Network Management Protocol: a protocol that's used for gathering data, widely used for network management and
-monitoring.
-
-WFO
-: <a href="https://workfloworchestrator.org/" target="_blank">Workflow Orchestrator</a>
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
new file mode 100644
index 00000000..5039c68c
--- /dev/null
+++ b/docs/source/glossary.rst
@@ -0,0 +1,43 @@
+Glossary of terms
+=================
+
+.. glossary::
+
+  BGP
+    Border Gateway Protocol: a path vector routing protocol described in
+    `RFC 4271 <https://datatracker.ietf.org/doc/html/rfc4271>`_.
+
+  CNAME
+    A type of DNS record that is used as an alias from one hostname to another
+
+  CRUD
+    Create, Read, Update, Delete
+
+  FQDN
+    Fully Quantified Domain Name
+
+  GSO
+    GÉANT Service Orchestrator
+
+  IPAM
+    IP Address Management
+
+  IS-IS
+    Intermediate System to Intermediate System: a routing protocol described in
+    `RFC 7142 <https://datatracker.ietf.org/doc/html/rfc7142>`_.
+
+  ISO
+    International Organisation for Standardisation
+
+  LSO
+    Lightweight Service Orchestrator
+
+  NET
+    Network Entity Title: used for {term}`IS-IS` routing.
+
+  SNMP
+    Simple Network Management Protocol: a protocol that's used for gathering data, widely used for network management
+    and monitoring.
+
+  WFO
+    `Workflow Orchestrator <https://workfloworchestrator.org/>`_
diff --git a/docs/source/static/custom.js b/docs/source/static/custom.js
new file mode 100644
index 00000000..184b5ae8
--- /dev/null
+++ b/docs/source/static/custom.js
@@ -0,0 +1,3 @@
+$(document).ready(function () {
+    $('a.external').attr('target', '_blank');
+});
-- 
GitLab