Skip to content

Commit efa2204

Browse files
gab-arrobogab-arrobo
authored
make several changes to docs, including its theme and update dependencies (omec-project#85)
* make several changes to docs, including its theme and update dependencies Signed-off-by: Arrobo, Gabriel <gabriel.arrobo@intel.com> * Address Copilot's comments Signed-off-by: Arrobo, Gabriel <gabriel.arrobo@intel.com> * Address Copilot's comments Signed-off-by: Arrobo, Gabriel <gabriel.arrobo@intel.com> * Address Copilot's comments Signed-off-by: Arrobo, Gabriel <gabriel.arrobo@intel.com> --------- Signed-off-by: Arrobo, Gabriel <gabriel.arrobo@intel.com>
1 parent ff4d22a commit efa2204

File tree

8 files changed

+376
-95
lines changed

8 files changed

+376
-95
lines changed

‎Makefile‎

Lines changed: 110 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
# SPDX-FileCopyrightText: 2026 Intel Corporation
12
# SPDX-FileCopyrightText: 2021 Open Networking Foundation <info@opennetworking.org>
23
# SPDX-License-Identifier: Apache-2.0
34

@@ -15,7 +16,16 @@ BUILDDIR ?= _build
1516
# name of python virtualenv that is used to run commands
1617
VENV_NAME := venv-docs
1718

18-
.PHONY: help Makefile test doc8 dict-check sort-dict license clean clean-all
19+
# Git repository information for versioning
20+
GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
21+
GIT_TAG := $(shell git describe --tags --exact-match 2>/dev/null || echo "")
22+
VERSION_TAGS := $(shell git tag --sort=-version:refname | head -3)
23+
24+
# Temporary directory for git worktrees
25+
WORKTREE_DIR := $(BUILDDIR)/worktrees
26+
27+
.PHONY: help Makefile test doc8 dict-check sort-dict license clean clean-all \
28+
multiversion add-nojekyll create-version-index version-info clean-worktrees
1929

2030
# Put it first so that "make" without argument is like "make help".
2131
help: $(VENV_NAME)
@@ -58,11 +68,106 @@ clean:
5868
clean-all: clean
5969
rm -rf $(VENV_NAME)
6070

61-
# build multiple versions
62-
multiversion: $(VENV_NAME) Makefile
71+
# Clean up git worktrees
72+
clean-worktrees:
73+
@echo "Cleaning up git worktrees..."
74+
@if [ -d "$(WORKTREE_DIR)" ]; then \
75+
for worktree in $(WORKTREE_DIR)/*; do \
76+
if [ -d "$$worktree" ]; then \
77+
echo "Removing worktree: $$worktree" ;\
78+
git worktree remove "$$worktree" 2>/dev/null || rm -rf "$$worktree" ;\
79+
fi ;\
80+
done ;\
81+
rmdir "$(WORKTREE_DIR)" 2>/dev/null || true ;\
82+
fi
83+
84+
# Ensure .nojekyll file exists for GitHub Pages
85+
add-nojekyll:
86+
@echo "Adding .nojekyll file for GitHub Pages..."
87+
@if [ -d "$(BUILDDIR)/html" ]; then \
88+
touch "$(BUILDDIR)/html/.nojekyll"; \
89+
echo "Created .nojekyll in $(BUILDDIR)/html/"; \
90+
fi
91+
@if [ -d "$(BUILDDIR)/multiversion" ]; then \
92+
touch "$(BUILDDIR)/multiversion/.nojekyll"; \
93+
echo "Created .nojekyll in $(BUILDDIR)/multiversion/"; \
94+
fi
95+
96+
# Build single version (current branch/tag)
97+
build: $(VENV_NAME) Makefile
98+
source $</bin/activate ; set -u ;\
99+
$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
100+
$(MAKE) add-nojekyll
101+
@echo "Documentation built successfully!"
102+
@echo "Open $(BUILDDIR)/html/index.html in your browser"
103+
104+
# Build multiple versions
105+
multiversion: $(VENV_NAME) Makefile clean-worktrees
106+
@echo "Building multi-version documentation..."
107+
@echo "Current branch: $(GIT_BRANCH)"
108+
@echo "Available tags: $(VERSION_TAGS)"
109+
rm -rf "$(BUILDDIR)/multiversion"
110+
mkdir -p "$(BUILDDIR)/multiversion"
111+
mkdir -p "$(WORKTREE_DIR)"
112+
@echo "Building latest version from current working directory..."
63113
source $</bin/activate ; set -u ;\
64-
sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
65-
cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html"
114+
$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/multiversion/latest" $(SPHINXOPTS)
115+
@if [ -n "$(VERSION_TAGS)" ]; then \
116+
for tag in $(VERSION_TAGS); do \
117+
echo "Building documentation for tag: $$tag using git worktree..." ;\
118+
worktree_path="$(WORKTREE_DIR)/$$tag" ;\
119+
if git worktree add "$$worktree_path" "$$tag" 2>/dev/null; then \
120+
echo "Created worktree for $$tag at $$worktree_path" ;\
121+
source $</bin/activate ; set -u ;\
122+
$(SPHINXBUILD) -b html "$$worktree_path" "$(BUILDDIR)/multiversion/$$tag" $(SPHINXOPTS) || echo "Warning: Failed to build $$tag" ;\
123+
git worktree remove "$$worktree_path" 2>/dev/null || echo "Warning: Failed to remove worktree $$worktree_path" ;\
124+
else \
125+
echo "Warning: Could not create worktree for tag $$tag" ;\
126+
fi ;\
127+
done ;\
128+
else \
129+
echo "No version tags found, building only latest version" ;\
130+
fi
131+
$(MAKE) create-version-index
132+
$(MAKE) add-nojekyll
133+
$(MAKE) clean-worktrees
134+
@echo "Multi-version documentation built successfully!"
135+
@echo "Open $(BUILDDIR)/multiversion/index.html in your browser"
136+
137+
# Create version selection index page
138+
create-version-index:
139+
@echo "Creating version index page..."
140+
@mkdir -p "$(BUILDDIR)/multiversion"
141+
@if [ ! -f "_templates/version-index.html" ]; then \
142+
echo "Error: Template file _templates/version-index.html not found"; \
143+
exit 1; \
144+
fi
145+
@cp "_templates/version-index.html" "$(BUILDDIR)/multiversion/index.html"
146+
@if [ -n "$(VERSION_TAGS)" ]; then \
147+
version_cards="" ;\
148+
for tag in $(VERSION_TAGS); do \
149+
version_cards="$$version_cards <a href=\"$$tag/\" class=\"version-card\">"$$'\n' ;\
150+
version_cards="$$version_cards <div class=\"version-title\">$$tag</div>"$$'\n' ;\
151+
version_cards="$$version_cards <div class=\"version-desc\">Release $$tag documentation</div>"$$'\n' ;\
152+
version_cards="$$version_cards </a>"$$'\n' ;\
153+
done ;\
154+
sed -i.bak "s|{{VERSION_CARDS}}|$$version_cards|g" "$(BUILDDIR)/multiversion/index.html" ;\
155+
rm -f "$(BUILDDIR)/multiversion/index.html.bak" ;\
156+
else \
157+
sed -i.bak "s|{{VERSION_CARDS}}||g" "$(BUILDDIR)/multiversion/index.html" ;\
158+
rm -f "$(BUILDDIR)/multiversion/index.html.bak" ;\
159+
fi
160+
161+
# Show current version information
162+
version-info:
163+
@echo "=== Version Information ==="
164+
@echo "Git Branch: $(GIT_BRANCH)"
165+
@echo "Git Tag: $(GIT_TAG)"
166+
@echo "Recent Tags: $(VERSION_TAGS)"
167+
@if [ -f "VERSION" ]; then echo "Version File: $$(cat VERSION)"; fi
168+
@echo "Build Directory: $(BUILDDIR)"
169+
@echo "Worktree Directory: $(WORKTREE_DIR)"
170+
@echo "=========================="
66171

67172
# Catch-all target: route all unknown targets to Sphinx using the new
68173
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).

‎_static/css/furo_custom.css‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
/*
2+
* SPDX-FileCopyrightText: 2026 Intel Corporation
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
/* Custom CSS for SD-Core Documentation with Furo theme */
7+
8+
/* Logo adjustments */
9+
.sidebar-logo img {
10+
max-height: 60px;
11+
width: auto;
12+
}
13+
14+
/* Custom admonition styling to match SD-Core branding */
15+
.admonition {
16+
border-left: 4px solid var(--color-brand-primary);
17+
}
18+
19+
/* Code block styling */
20+
.highlight {
21+
border-radius: 6px;
22+
}
23+
24+
/* Custom footer styling */
25+
.footer-content {
26+
text-align: center;
27+
}
28+
29+
/* Version selector styling for multi-version documentation */
30+
.version-selector {
31+
margin-bottom: 1rem;
32+
}
33+
34+
/* Custom styling for tables */
35+
table.docutils {
36+
border-collapse: collapse;
37+
margin: 1rem 0;
38+
}
39+
40+
table.docutils th,
41+
table.docutils td {
42+
border: 1px solid var(--color-foreground-border);
43+
padding: 0.5rem;
44+
}
45+
46+
table.docutils th {
47+
background-color: var(--color-background-secondary);
48+
font-weight: bold;
49+
}
50+
51+
/* Responsive images */
52+
img {
53+
max-width: 100%;
54+
height: auto;
55+
}
56+
57+
/* Custom styling for network diagrams */
58+
.nwdiag,
59+
.rackdiag {
60+
text-align: center;
61+
margin: 1rem 0;
62+
}

‎_static/css/rtd_theme_mods.css‎

Lines changed: 0 additions & 23 deletions
This file was deleted.

‎_templates/meta_refresh.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<!--
22
SPDX-FileCopyrightText: © 2020 Open Networking Foundation <support@opennetworking.org>
33
SPDX-License-Identifier: Apache-2.0
4-
--!>
4+
-->
55
<html><head>
66
<meta charset="UTF-8">
77
<meta http-equiv="refresh" content="0;url=main/index.html" />

‎_templates/version_index.html‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
<!--
2+
SPDX-FileCopyrightText: © 2026 Intel Corporation
3+
SPDX-License-Identifier: Apache-2.0
4+
-->
5+
<!DOCTYPE html>
6+
<html lang="en">
7+
<head>
8+
<meta charset="UTF-8">
9+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
10+
<title>SD-Core Documentation Versions</title>
11+
<link rel="icon" href="latest/_static/sdcore-favicon-128.png">
12+
<style>
13+
body {
14+
font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
15+
max-width: 800px;
16+
margin: 2rem auto;
17+
padding: 0 1rem;
18+
line-height: 1.6;
19+
background-color: #f8f9fa;
20+
}
21+
.header {
22+
text-align: center;
23+
margin-bottom: 3rem;
24+
background: white;
25+
padding: 2rem;
26+
border-radius: 12px;
27+
box-shadow: 0 2px 10px rgba(0,0,0,0.1);
28+
}
29+
.logo {
30+
max-width: 200px;
31+
margin-bottom: 1rem;
32+
}
33+
.version-grid {
34+
display: grid;
35+
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
36+
gap: 1.5rem;
37+
margin: 2rem 0;
38+
}
39+
.version-card {
40+
border: 2px solid #e9ecef;
41+
border-radius: 12px;
42+
padding: 2rem;
43+
text-decoration: none;
44+
color: inherit;
45+
transition: all 0.3s ease;
46+
background: #fff;
47+
box-shadow: 0 2px 10px rgba(0,0,0,0.1);
48+
}
49+
.version-card:hover {
50+
border-color: #1f5582;
51+
box-shadow: 0 8px 25px rgba(31, 85, 130, 0.15);
52+
transform: translateY(-2px);
53+
text-decoration: none;
54+
}
55+
.version-title {
56+
font-size: 1.3rem;
57+
font-weight: 600;
58+
margin-bottom: 0.5rem;
59+
color: #1f5582;
60+
}
61+
.version-desc {
62+
color: #6c757d;
63+
font-size: 0.95rem;
64+
}
65+
.latest-badge {
66+
background: #28a745;
67+
color: white;
68+
padding: 0.25rem 0.5rem;
69+
border-radius: 4px;
70+
font-size: 0.8rem;
71+
margin-left: 0.5rem;
72+
}
73+
.footer {
74+
text-align: center;
75+
margin-top: 3rem;
76+
padding-top: 2rem;
77+
border-top: 1px solid #e9ecef;
78+
color: #6c757d;
79+
background: white;
80+
padding: 2rem;
81+
border-radius: 12px;
82+
box-shadow: 0 2px 10px rgba(0,0,0,0.1);
83+
}
84+
.footer a {
85+
color: #1f5582;
86+
text-decoration: none;
87+
}
88+
.footer a:hover {
89+
text-decoration: underline;
90+
}
91+
</style>
92+
</head>
93+
<body>
94+
<div class="header">
95+
<img src="latest/_static/sdcore.svg" alt="SD-Core" class="logo" onerror="this.style.display='none'">
96+
<h1>SD-Core Documentation</h1>
97+
<p>Select a version to view the documentation</p>
98+
</div>
99+
<div class="version-grid">
100+
<a href="latest/" class="version-card">
101+
<div class="version-title">Latest<span class="latest-badge">CURRENT</span></div>
102+
<div class="version-desc">Latest development version from main branch</div>
103+
</a>
104+
{{VERSION_CARDS}}
105+
</div>
106+
<div class="footer">
107+
<p>&copy; 2021-current, <a href="https://opennetworking.org/">Open Networking Foundation</a></p>
108+
<p>
109+
<a href="https://github.com/omec-project">GitHub</a> |
110+
<a href="https://aetherproject.org/">Aether Project</a> |
111+
<a href="https://opennetworking.org/">ONF</a>
112+
</p>
113+
</div>
114+
</body>
115+
</html>

‎_templates/versions.html‎

Lines changed: 0 additions & 31 deletions
This file was deleted.

0 commit comments

Comments
 (0)