kevinveenbirkenbach/computer-playbook
1
0
Fork 0
mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2025-03-29 04:23:34 +01:00
Code Issues Packages Projects Releases Wiki Activity

Optimized subfolders

Browse Source
This commit is contained in:
Kevin Veen-Birkenbach 2025-03-17 01:42:01 +01:00
parent d36fc0c916
commit 5677a91e82
No known key found for this signature in database
GPG Key ID: 44D8F11FD62F878E
2 changed files with 38 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
sphinx/_templates/local_md_files.html
View File

@ -13,7 +13,19 @@
{% if local_md_headings %} {% if local_md_headings %}
<div class="local-md-headings"> <div class="local-md-headings">
<h3>Overview</h3> <h3>Current Folder</h3>
{{ render_headings(local_md_headings) }} {{ render_headings(local_md_headings) }}
</div> </div>
{% endif %} {% endif %}
{% if local_subfolders %}
<div class="local-subfolders">
<h3>Subfolders</h3>
<ul>
{% for item in local_subfolders %}
<li><a href="{{ pathto(item.link) }}">{{ item.text }}</a></li>
{% endfor %}
</ul>
</div>
{% endif %}

48
sphinx/extensions/local_subfolders.py
View File

@ -1,7 +1,6 @@
import os import os
import re import re
from sphinx.util import logging from sphinx.util import logging
from docutils.parsers.rst import Directive
from .nav_utils import natural_sort_key, extract_headings_from_file, group_headings, sort_tree, MAX_HEADING_LEVEL, DEFAULT_MAX_NAV_DEPTH from .nav_utils import natural_sort_key, extract_headings_from_file, group_headings, sort_tree, MAX_HEADING_LEVEL, DEFAULT_MAX_NAV_DEPTH
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
@ -9,9 +8,11 @@ logger = logging.getLogger(__name__)
def collect_subfolder_tree(dir_path, base_url, current_depth, max_depth): def collect_subfolder_tree(dir_path, base_url, current_depth, max_depth):
""" """
Recursively collects navigation items from subdirectories. Recursively collects navigation items from subdirectories.
For each subfolder, it looks for a candidate file (prefer "index.rst" then "README.md") For each subfolder, it looks for a candidate file (prefer "index.rst" then "README.md").
and extracts its first level‑1 heading as the title. If no candidate or heading is found, Only subfolders with such a file will be included.
the folder name is used. If a candidate is found, the first level‑1 heading from that file is used as the title;
if no heading is found, the folder name is used.
The link is built pointing directly to the candidate file (by its base name) rather than the folder.
Returns a list representing the subfolder tree. Returns a list representing the subfolder tree.
""" """
items = [] items = []
@ -24,32 +25,34 @@ def collect_subfolder_tree(dir_path, base_url, current_depth, max_depth):
if os.path.isfile(candidate_path): if os.path.isfile(candidate_path):
candidate = candidate_path candidate = candidate_path
break break
# Only include the folder if a candidate file was found.
if candidate: if candidate:
headings = extract_headings_from_file(candidate, max_level=MAX_HEADING_LEVEL) headings = extract_headings_from_file(candidate, max_level=MAX_HEADING_LEVEL)
title = headings[0]['text'] if headings else item title = headings[0]['text'] if headings else item
else: # Use the candidate file's base name as link target.
title = item candidate_base = os.path.splitext(os.path.basename(candidate))[0]
link = os.path.join(base_url, item) link = os.path.join(base_url, item, candidate_base)
entry = { entry = {
'level': 1, 'level': 1,
'text': title, 'text': title,
'link': link, 'link': link,
'anchor': '', 'anchor': '',
'priority': 0, 'priority': 0,
'filename': item 'filename': item
} }
if current_depth < max_depth: if current_depth < max_depth:
children = collect_subfolder_tree(full_path, os.path.join(base_url, item), current_depth + 1, max_depth) children = collect_subfolder_tree(full_path, os.path.join(base_url, item), current_depth + 1, max_depth)
if children: if children:
entry['children'] = children entry['children'] = children
items.append(entry) items.append(entry)
return items return items
def add_local_subfolders(app, pagename, templatename, context, doctree): def add_local_subfolders(app, pagename, templatename, context, doctree):
""" """
Collects a tree of subfolder navigation items from the current directory. Collects a tree of subfolder navigation items from the current directory.
For each subfolder, the title is determined by scanning for a candidate file (prefer "index.rst" then "README.md") For each subfolder, the title is determined by scanning for a candidate file
and extracting its first level‑1 heading, or using the folder name if none is found. (prefer "index.rst" then "README.md") and extracting its first level‑1 heading,
or using the folder name if none is found.
The resulting tree is stored in context['local_subfolders']. The resulting tree is stored in context['local_subfolders'].
""" """
srcdir = app.srcdir srcdir = app.srcdir
@ -66,6 +69,5 @@ def add_local_subfolders(app, pagename, templatename, context, doctree):
context['local_subfolders'] = subfolder_tree context['local_subfolders'] = subfolder_tree
def setup(app): def setup(app):
# Do not add the config value here to avoid conflicts.
app.connect('html-page-context', add_local_subfolders) app.connect('html-page-context', add_local_subfolders)
return {'version': '0.1', 'parallel_read_safe': True} return {'version': '0.1', 'parallel_read_safe': True}