From 74edb197debbcd7ce0a528bd67a709e1fdae5f2f Mon Sep 17 00:00:00 2001
From: Kevin Veen-Birkenbach <kevin@veen.world>
Date: Sun, 16 Mar 2025 22:14:34 +0100
Subject: [PATCH] Implemented subfolders in navigation
---
LICENSE.md | 9 +++--
sphinx/local_md_files.py | 76 +++++++++++++++++++++++++++++++++-------
2 files changed, 67 insertions(+), 18 deletions(-)
diff --git a/LICENSE.md b/LICENSE.md
index a141e5df..34679fa0 100644
--- a/LICENSE.md
+++ b/LICENSE.md
@@ -1,11 +1,10 @@
-# License Agreement
-## CyMaIS NonCommercial License (CNCL)
+# CyMaIS NonCommercial License (CNCL)
-### Definitions
+## Definitions
- **"Software":** Refers to *"[CyMaIS - Cyber Master Infrastructure Solution](https://cymais.cloud/)"* and its associated source code.
- **"Commercial Use":** Any use of the Software intended for direct or indirect financial gain, including but not limited to sales, rentals, or provision of services.
-### Provisions
+## Provisions
1. **Attribution of the Original Licensor:** In any distribution or publication of the Software or derivative works, the original licensor, *Kevin Veen-Birkenbach, Email: [license@veen.world](mailto:license@veen.world), Website: [https://www.veen.world/](https://www.veen.world/)* must be explicitly named.
@@ -24,5 +23,5 @@
7. **Ownership of Rights:** All rights, including copyright, trademark, and other forms of intellectual property related to the Software, belong exclusively to Kevin Veen-Birkenbach.
-### Consent
+## Consent
By using, modifying, or distributing the Software, you agree to these terms.
\ No newline at end of file
diff --git a/sphinx/local_md_files.py b/sphinx/local_md_files.py
index a5ba13cc..db3053bf 100644
--- a/sphinx/local_md_files.py
+++ b/sphinx/local_md_files.py
@@ -4,8 +4,9 @@ from sphinx.util import logging
logger = logging.getLogger(__name__)
-# Set the maximum heading level to include (e.g., include headings up to H3 for Markdown)
+# Set the maximum heading level for Markdown headings
MAX_HEADING_LEVEL = 3
+DEFAULT_MAX_NAV_DEPTH = 2 # Default maximum navigation depth; configurable via conf.py
def natural_sort_key(text):
"""
@@ -16,8 +17,9 @@ def natural_sort_key(text):
def extract_headings_from_file(filepath, max_level=MAX_HEADING_LEVEL):
"""
- Extract headings from a file. For Markdown files, look for lines starting with '#' (up to max_level).
- For reStructuredText files, look for a line that is immediately followed by an underline made of punctuation.
+ Extract headings from a file.
+ For Markdown files, look for lines starting with '#' (up to max_level).
+ For reStructuredText files, look for a line immediately followed by an underline made of punctuation.
"""
headings = []
ext = os.path.splitext(filepath)[1].lower()
@@ -26,13 +28,11 @@ def extract_headings_from_file(filepath, max_level=MAX_HEADING_LEVEL):
if ext == '.md':
in_code_block = False
for line in f:
- # Toggle code block state if a line starts with ```
if line.strip().startswith("```"):
in_code_block = not in_code_block
continue
if in_code_block:
continue
- # Match Markdown headings: one or more '#' followed by a space and the title.
match = re.match(r'^(#{1,})\s+(.*)$', line)
if match:
level = len(match.group(1))
@@ -43,12 +43,11 @@ def extract_headings_from_file(filepath, max_level=MAX_HEADING_LEVEL):
headings.append({'level': level, 'text': heading_text, 'anchor': anchor})
elif ext == '.rst':
lines = f.readlines()
- # Look for reST headings: a line followed by an underline made of punctuation.
for i in range(len(lines)-1):
text_line = lines[i].rstrip("\n")
underline = lines[i+1].rstrip("\n")
if len(underline) >= 3 and re.fullmatch(r'[-=~\^\+"\'`]+', underline):
- level = 1 # default level; you could adjust based on the punctuation if needed
+ level = 1 # default level; adjust if needed
heading_text = text_line.strip()
anchor = re.sub(r'\s+', '-', heading_text.lower())
anchor = re.sub(r'[^a-z0-9\-]', '', anchor)
@@ -77,11 +76,50 @@ def group_headings(headings):
def sort_tree(tree):
"""
- Sorts a list of headings (and their children) first by their 'priority' (if defined, default 1)
+ Sorts a list of headings (and their children) first by their 'priority' (default 1)
and then by the natural sort key of their text.
"""
tree.sort(key=lambda x: (x.get('priority', 1), natural_sort_key(x['text'])))
+def collect_nav_items(dir_path, base_url, current_depth, max_depth):
+ """
+ Recursively collects navigation items from subdirectories.
+ For each subdirectory, if an 'index.rst' exists (preferred) or a 'readme.md' exists,
+ the first heading from that file is used as the title.
+ """
+ nav_items = []
+ # Look for candidate file in this subdirectory (prefer index.rst, then readme.md)
+ candidate = None
+ for cand in ['index.rst', 'readme.md']:
+ candidate_path = os.path.join(dir_path, cand)
+ if os.path.isfile(candidate_path):
+ candidate = cand
+ break
+ if candidate:
+ candidate_path = os.path.join(dir_path, candidate)
+ headings = extract_headings_from_file(candidate_path)
+ if headings:
+ title = headings[0]['text']
+ else:
+ title = os.path.splitext(candidate)[0].capitalize()
+ # Build link relative to base_url
+ link = os.path.join(base_url, os.path.splitext(candidate)[0])
+ nav_items.append({
+ 'level': 1,
+ 'text': title,
+ 'link': link,
+ 'anchor': '',
+ 'priority': 0
+ })
+ # Recurse into subdirectories if within max_depth
+ if current_depth < max_depth:
+ for item in os.listdir(dir_path):
+ full_path = os.path.join(dir_path, item)
+ if os.path.isdir(full_path):
+ sub_base_url = os.path.join(base_url, item)
+ nav_items.extend(collect_nav_items(full_path, sub_base_url, current_depth + 1, max_depth))
+ return nav_items
+
def add_local_md_headings(app, pagename, templatename, context, doctree):
srcdir = app.srcdir
directory = os.path.dirname(pagename)
@@ -91,20 +129,28 @@ def add_local_md_headings(app, pagename, templatename, context, doctree):
context['local_md_headings'] = []
return
- # List all files in the directory.
+ max_nav_depth = getattr(app.config, 'local_nav_max_depth', DEFAULT_MAX_NAV_DEPTH)
+
+ # Collect navigation items from subdirectories only
+ nav_items = []
+ for item in os.listdir(abs_dir):
+ full_path = os.path.join(abs_dir, item)
+ if os.path.isdir(full_path):
+ nav_items.extend(collect_nav_items(full_path, os.path.join(directory, item), current_depth=1, max_depth=max_nav_depth))
+
+ # Process files in the current directory.
files = os.listdir(abs_dir)
files_lower = [f.lower() for f in files]
- # If both index.rst and README.md exist, filter out README.md (case-insensitive)
+ # If both index.rst and readme.md exist in the current directory, keep only index.rst.
if "index.rst" in files_lower:
files = [f for f in files if f.lower() != "readme.md"]
-
local_md_headings = []
for file in files:
if file.endswith('.md') or file.endswith('.rst'):
filepath = os.path.join(abs_dir, file)
headings = extract_headings_from_file(filepath)
- # Determine file priority: index and readme get priority 0; others 1.
basename, _ = os.path.splitext(file)
+ # Set priority: index/readme files get priority 0.
if basename.lower() in ['index', 'readme']:
priority = 0
else:
@@ -118,10 +164,14 @@ def add_local_md_headings(app, pagename, templatename, context, doctree):
'anchor': heading['anchor'],
'priority': priority
})
- tree = group_headings(local_md_headings)
+ # Combine current directory items with subdirectory nav items.
+ # If an index or readme from the current directory exists, it will be included only once.
+ all_items = local_md_headings + nav_items
+ tree = group_headings(all_items)
sort_tree(tree)
context['local_md_headings'] = tree
def setup(app):
+ app.add_config_value('local_nav_max_depth', DEFAULT_MAX_NAV_DEPTH, 'env')
app.connect('html-page-context', add_local_md_headings)
return {'version': '0.1', 'parallel_read_safe': True}