Reworked directories structure and added dark mode

.github/workflows/project_automation.yml

@@ -59,6 +59,6 @@ jobs:
           gh_token: ${{ secrets.MY_GITHUB_TOKEN }}
           # user: ghostbsd
           organization: ghostbsd
-          project_id: 4
+          project_id: 5
           resource_node_id: ${{ github.event.pull_request.node_id }}
           status_value: ${{ env.in_review }}

.readthedocs.yaml

@@ -11,7 +11,7 @@ build:
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
-  configuration: source/conf.py
+  configuration: conf.py
 
   # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
   # builder: "dirhtml"

Makefile

@@ -5,7 +5,7 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
+SOURCEDIR     = .
 BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".

README.md

@@ -14,11 +14,10 @@ Use a local development server that regenerates the output whenever the input ch
 
 ```
 git clone [email protected]:ghostbsd/documentation.git
-sudo pkg install -y py311-pip py311-sphinx py311-myst-parser py311-sphinx_rtd_theme gmake
-pip install docutils==0.16
-sudo pip install sphinx-autobuild
+sudo pkg install -y py311-pip
+sudo pip install sphinx sphinx-rtd-theme myst-parser sphinx-autobuild
 cd documentation
-sphinx-autobuild source build/html
+sphinx-autobuild . build/html
 ```
 
 Then, open http://127.0.0.1:8000/index.html in a web browser. It will be regenerated and refreshed whenever a changed file is saved.
@@ -30,5 +29,4 @@ One can also generate documentation, in various output formats, locally:
 ```
 gmake html
 gmake epub
-
 ```

_static/dark_mode.css

@@ -0,0 +1,190 @@
+/* Dark mode styles, applied only when body has the dark-mode class */
+body.dark-mode {
+    background-color: #252525; /* Slightly lighter dark gray */
+    color: #e0e0e0; /* Light gray text */
+}
+
+body.dark-mode .wy-nav-top {
+    background-color: #2b2b2b; /* Darker header */
+}
+
+body.dark-mode .wy-nav-side {
+    background-color: #2b2b2b; /* Dark sidebar */
+}
+
+body.dark-mode .wy-menu-vertical a {
+    color: #e0e0e0; /* Light sidebar links */
+}
+
+body.dark-mode .wy-menu-vertical a:hover {
+    background-color: #3c3c3c; /* Hover effect for general links */
+}
+
+body.dark-mode .wy-nav-content {
+    background-color: #252525; /* Match the body background */
+}
+
+body.dark-mode h1,
+body.dark-mode h2,
+body.dark-mode h3,
+body.dark-mode h4,
+body.dark-mode h5,
+body.dark-mode h6 {
+    color: #ffffff; /* White headings */
+}
+
+body.dark-mode a {
+    color: #4da8da; /* Light blue links */
+}
+
+body.dark-mode a:hover {
+    color: #66b3ff; /* Lighter blue on hover */
+}
+
+body.dark-mode pre {
+    background-color: #2b2b2b; /* Dark code background */
+    color: #e0e0e0; /* Light code text */
+    border: 1px solid #3c3c3c;
+}
+
+/* Optional: Style the toggle button */
+button {
+    padding: 8px 16px;
+    background-color: #4da8da;
+    color: white;
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+}
+
+button:hover {
+    background-color: #66b3ff;
+}
+
+body.dark-mode button {
+    background-color: #2b2b2b;
+    color: #e0e0e0;
+}
+
+body.dark-mode button:hover {
+    background-color: #3c3c3c;
+}
+
+/* Ensure proper layout in wy-breadcrumbs */
+.wy-breadcrumbs {
+    position: relative;
+    padding: 0 10px;
+    overflow: hidden; /* Contain floated elements */
+    white-space: nowrap; /* Prevent wrapping */
+}
+
+/* Style <li> elements to stay inline */
+.wy-breadcrumbs li {
+    display: inline-block;
+    margin-right: 5px;
+    vertical-align: middle; /* Align breadcrumb items */
+}
+
+/* Style wy-breadcrumbs-aside to keep "View page source" on the right */
+.wy-breadcrumbs-aside {
+    float: right; /* Matches theme's default behavior */
+    display: inline-block;
+    margin-left: 10px; /* Space from button */
+}
+
+/* Ensure "View page source" aligns properly */
+.wy-breadcrumbs-aside a {
+    display: inline-block;
+    vertical-align: middle;
+}
+
+/* Style the button directly in wy-breadcrumbs to stay on the right */
+.wy-breadcrumbs button {
+    float: right; /* Pin to the right */
+    margin-left: 10px; /* Space from breadcrumb text */
+    margin-right: 10px; /* Space before "View page source" */
+    vertical-align: middle; /* Align with other items */
+}
+
+/* Keep <a class="icon icon-home">GhostBSD</a> white in both modes */
+.wy-side-nav-search .icon.icon-home:not([aria-label="Home"]) {
+    color: #ffffff; /* White in light mode */
+}
+
+body.dark-mode .wy-side-nav-search .icon.icon-home:not([aria-label="Home"]) {
+    color: #ffffff; /* White in dark mode */
+}
+
+/* Fix white background of .toctree-l1.current in dark mode */
+body.dark-mode .wy-menu-vertical .toctree-l1.current {
+    background-color: #3c3c3c; /* Slightly lighter than sidebar */
+}
+
+/* Darken background of <a class="reference internal current"> in dark mode */
+body.dark-mode .wy-menu-vertical a.reference.internal.current {
+    background-color: #333333; /* Darker than #3c3c3c */
+}
+
+/* Ensure .toctree-l2 <a> fills the li and darkens on hover */
+.wy-menu-vertical .toctree-l2 a {
+    display: block; /* Ensure it fills the li */
+}
+
+body.dark-mode .wy-menu-vertical .toctree-l2 a:hover {
+    background-color: #2a2a2a !important; /* Darker than #3c3c3c, override all */
+}
+
+/* Ensure <a> in sidebar fills its parent <li> */
+.wy-menu-vertical .toctree-l1 a {
+    display: block; /* Ensure it fills the li */
+}
+
+/* Ensure <a> in toctree-l3 fills its parent <li> */
+.wy-menu-vertical .toctree-l3 a {
+    display: block; /* Ensure it fills the li */
+}
+
+/* Darken <a href="#"> inside .toctree-l1.current[aria-expanded="true"] at all times */
+body.dark-mode .wy-menu-vertical .toctree-l1.current[aria-expanded="true"] a[href="#"] {
+    background-color: #2b2b2b; /* Darker than #3c3c3c, constant background */
+}
+
+/* Highly specific override for .toctree-l2.current in dark mode */
+body.dark-mode .wy-nav-side .wy-menu.wy-menu-vertical ul li.current.toctree-l2 {
+    background-color: #3c3c3c !important; /* Reordered classes for specificity */
+}
+
+/* Ensure li.toctree-l2.current has the correct background in dark mode */
+body.dark-mode .wy-menu-vertical li.toctree-l2.current {
+    background-color: #3c3c3c !important;
+}
+
+/* Ensure the <a> inside li.toctree-l2.current does not override the background */
+body.dark-mode .wy-menu-vertical li.toctree-l2.current a {
+    background-color: transparent !important;
+}
+
+/* Ensure nested <ul> inside li.toctree-l2.current does not override the background */
+body.dark-mode .wy-menu-vertical li.toctree-l2.current ul {
+    background-color: transparent !important;
+}
+
+/* Ensure hover effect for toctree-l3 links in dark mode */
+body.dark-mode .wy-nav-side .wy-menu.wy-menu-vertical li.toctree-l3 a:hover {
+    background-color: #2a2a2a !important; /* Darker than #3c3c3c, override all */
+}
+
+/* Prevent parent li.toctree-l3 from interfering with hover effect */
+body.dark-mode .wy-menu-vertical li.toctree-l3:hover {
+    background-color: transparent !important;
+}
+
+/* Ensure li.toctree-l3.current has the correct background in dark mode */
+body.dark-mode .wy-menu-vertical li.toctree-l3.current {
+    background-color: #3c3c3c !important; /* Matches toctree-l2.current */
+}
+
+/* Ensure the <a> inside li.toctree-l3.current does not override the background */
+body.dark-mode .wy-menu-vertical li.toctree-l3.current a {
+    background-color: transparent !important;
+}

_static/dark_mode.js

@@ -0,0 +1,44 @@
+document.addEventListener('DOMContentLoaded', function () {
+    const breadcrumbs = document.querySelector('.wy-breadcrumbs');
+    if (!breadcrumbs) {
+        console.error('Breadcrumbs element (.wy-breadcrumbs) not found!');
+        return;
+    }
+
+    const toggleButton = document.createElement('button');
+    toggleButton.style.marginLeft = '20px';
+
+    function updateButtonText() {
+        toggleButton.textContent = document.body.classList.contains('dark-mode') ? 'Light Mode' : 'Dark Mode';
+    }
+
+    breadcrumbs.appendChild(toggleButton);
+
+    const prefersDarkMode = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    const savedPreference = localStorage.getItem('darkMode');
+
+    if (savedPreference !== null) {
+        if (savedPreference === 'true') {
+            document.body.classList.add('dark-mode');
+        } else {
+            document.body.classList.remove('dark-mode');
+        }
+    } else if (prefersDarkMode) {
+        document.body.classList.add('dark-mode');
+    }
+
+    updateButtonText();
+
+    toggleButton.addEventListener('click', function () {
+        document.body.classList.toggle('dark-mode');
+        localStorage.setItem('darkMode', document.body.classList.contains('dark-mode'));
+        updateButtonText();
+    });
+
+    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
+        if (localStorage.getItem('darkMode') === null) {
+            document.body.classList.toggle('dark-mode', e.matches);
+            updateButtonText();
+        }
+    });
+});

source/conf.py → conf.py

@@ -10,14 +10,14 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
+import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
 # -- Project information -----------------------------------------------------
 
 project = 'GhostBSD'
-copyright = '2021, GhostBSD'
+copyright = '2025, GhostBSD'
 author = 'Eric Turgeon'
 
 
@@ -27,7 +27,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'myst_parser'
+    'myst_parser',
+    'sphinx_rtd_theme'
 ]
 
 myst_heading_anchors = 3
@@ -57,7 +58,17 @@
 #
 html_theme = 'sphinx_rtd_theme'
 
+# Display "Edit on GitHub"
+html_context = {
+  'display_github': True,
+  'github_user': 'ghostbsd',
+  'github_repo': 'documentation',
+  'github_version': 'master/',
+}
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+html_css_files = ['dark_mode.css']
+html_js_files = ['dark_mode.js']

make.bat

@@ -7,7 +7,7 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set SOURCEDIR=source
+set SOURCEDIR=.
 set BUILDDIR=build
 
 if "%1" == "" goto help