Stable | New features and SEO

Author: pritkc

doc/sphinx/Makefile

@@ -29,7 +29,7 @@ else
   OPEN_CMD := start
 endif
 
-.PHONY: help clean doc-deps doc-html doc-clean-dirs doc-doxygen doc-all $(SPHINX_TARGETS) doc-latexpdf doc-latexpdf
+.PHONY: help clean doc-deps doc-html doc-clean-dirs doc-doxygen doc-all $(SPHINX_TARGETS) doc-latexpdf doc-custom
 
 # Default target
 help:
@@ -120,6 +120,7 @@ doc-all: doc-clean-dirs doc-doxygen doc-deps doc-html doc-latexpdf
 	@echo "  PDF:  $(PDFDIR)/MOLE-docs.pdf"
 	@echo "  API:  ../doxygen/cpp/"
 	@echo "================================================================"
+
 # Explicit Sphinx targets
 $(SPHINX_TARGETS):
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)

doc/sphinx/README.md

@@ -112,6 +112,13 @@ Before building the documentation, ensure you have:
    python3 -m pip install -r requirements.txt
    ```
 
+   Some additional packages have been added to enhance documentation features:
+   - `sphinx-togglebutton`: For collapsible content
+   - `sphinx-fontawesome`: For FontAwesome icons
+   - `sphinxcontrib-mermaid`: For Mermaid.js diagrams
+   - `sphinxext-altair`: For Altair chart integration
+   - `Pillow`: For image processing including dark mode logo
+
 ### Building Steps
 
 All commands should be run from the `doc/sphinx` directory:

doc/sphinx/requirements.txt

@@ -20,20 +20,20 @@
 # ======= Sphinx =======
 
 # Core Sphinx
-sphinx>=5.3,<7                   # Extended version range for Python 3.12
-docutils>=0.18                   # More flexible version requirement
+sphinx<8.0
+docutils<0.20
 Pillow                          # Required for imghdr module
 setuptools                      # Required for pkg_resources
 
 # Theme
-sphinx-book-theme>=0.4.0         # Book theme (primary)
-sphinx_rtd_theme>=1.0            # Read the Docs theme (alternative)
+sphinx-book-theme
+sphinx-design
 
 # Extensions used in conf.py
 breathe>=4.30                    # C++ documentation integration
-myst-parser[linkify]>=0.14.0    # Markdown support
-sphinx-design                    # UI components
-sphinx-copybutton>=0.5.0         # Copy button for code blocks
+myst-parser
+sphinx-rtd-theme
+sphinx-copybutton
 sphinxcontrib-bibtex>=2.5       # Bibliography support
 sphinxcontrib-katex             # Math rendering
 standard-imghdr
@@ -48,4 +48,36 @@ sphinx-hoverxref>=0.3b1         # Hover tooltips for references
 # Documentation Dependencies
 sphinxcontrib-matlabdomain>=0.22.0,<0.23.0  # Pin version for Python 3.12 compatibility
 sphinxcontrib-serializinghtml
-sphinxcontrib-htmlhelp
+sphinxcontrib-htmlhelp
+
+# Core documentation packages
+sphinx==6.2.1
+sphinx-book-theme==1.1.4
+myst-parser==3.0.1
+breathe==4.35.0
+
+# Theme enhancements
+sphinx-design==0.6.1
+sphinx-copybutton==0.5.2
+sphinx-togglebutton==0.3.2
+
+# Additional features
+sphinxcontrib-bibtex==2.5.0
+sphinxcontrib-katex==0.9.10
+sphinxcontrib-jquery==4.1
+
+# MATLAB domain
+sphinxcontrib-matlabdomain==0.22.1
+
+# Image handling
+Pillow==11.2.1
+
+# HTTP requests for contributors extension
+requests==2.32.3
+
+# For PDF generation
+latexcodec==3.0.0
+pygments==2.19.1
+
+# Development tools
+jinja2==3.1.6

doc/sphinx/source/_ext/generate_sitemap.py

@@ -0,0 +1,77 @@
+"""
+Sphinx extension to generate a sitemap.xml for the HTML website.
+"""
+
+import os
+from datetime import datetime
+from pathlib import Path
+from jinja2 import Environment, FileSystemLoader
+
+def generate_sitemap(app, exception):
+    """
+    Generate sitemap.xml in the HTML build directory.
+    """
+    if exception is not None or app.builder.name != "html":
+        return
+
+    try:
+        # Get configuration variables
+        sitemap_url_base = app.config.html_baseurl or "https://mole-pdes.readthedocs.io"
+        if not sitemap_url_base.endswith("/"):
+            sitemap_url_base += "/"
+
+        # Get template directory and set up jinja2 environment
+        template_dir = os.path.join(app.srcdir, "_templates")
+        env = Environment(loader=FileSystemLoader(template_dir))
+        template = env.get_template("sitemap.xml")
+
+        # Build a list of all HTML files in the build directory
+        html_dir = app.outdir
+        build_path = Path(html_dir)
+        
+        # Create a list of pages for the sitemap
+        pages = []
+        
+        for path in build_path.rglob("*.html"):
+            # Get the relative path from the build directory
+            rel_path = path.relative_to(build_path)
+            url = sitemap_url_base + str(rel_path).replace(os.sep, "/")
+            
+            # Get the last modification time of the file
+            last_mod = datetime.fromtimestamp(path.stat().st_mtime).strftime("%Y-%m-%d")
+            
+            # Skip some files that shouldn't be in the sitemap
+            if any(part.startswith("_") for part in rel_path.parts):
+                continue
+                
+            # Add the page to the list
+            pages.append({
+                "loc": url,
+                "lastmod": last_mod
+            })
+            
+        # Render the sitemap
+        sitemap_content = template.render(pages=pages)
+        
+        # Write the sitemap to the build directory
+        sitemap_path = os.path.join(html_dir, "sitemap.xml")
+        with open(sitemap_path, "w") as f:
+            f.write(sitemap_content)
+            
+        print(f"Generated sitemap.xml with {len(pages)} pages")
+        
+    except Exception as e:
+        print(f"Error generating sitemap.xml: {e}")
+
+def setup(app):
+    """
+    Set up the Sphinx extension.
+    """
+    # Run after the HTML build is finished
+    app.connect("build-finished", generate_sitemap)
+    
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    } 

doc/sphinx/source/_ext/github_contributors.py

@@ -0,0 +1,103 @@
+"""
+Sphinx extension to display GitHub contributors.
+"""
+
+import os
+import json
+import requests
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+
+
+class GithubContributorsDirective(Directive):
+    """
+    Directive to display GitHub contributors.
+    
+    Usage:
+    .. github-contributors:: owner/repo
+       :max: 10
+       :columns: 4
+    """
+    
+    required_arguments = 1
+    optional_arguments = 0
+    option_spec = {
+        'max': directives.positive_int,
+        'columns': directives.positive_int,
+        'exclude': directives.unchanged,
+    }
+    has_content = False
+    
+    def run(self):
+        # Parse arguments
+        repo_path = self.arguments[0]
+        max_contributors = self.options.get('max', 100)
+        columns = self.options.get('columns', 4)
+        exclude_logins = self.options.get('exclude', '').split(',')
+        exclude_logins = [login.strip() for login in exclude_logins if login.strip()]
+        
+        try:
+            # Use GitHub API to get contributors
+            api_url = f"https://api.github.com/repos/{repo_path}/contributors?per_page={max_contributors}"
+            
+            # Check for GitHub token in environment variables
+            github_token = os.environ.get('GITHUB_TOKEN', '')
+            headers = {}
+            if github_token:
+                headers['Authorization'] = f'token {github_token}'
+                
+            response = requests.get(api_url, headers=headers)
+            response.raise_for_status()
+            contributors = response.json()
+            
+            # Filter excluded contributors
+            contributors = [c for c in contributors if c['login'] not in exclude_logins]
+            
+            # Create a container div for the contributors grid
+            container = nodes.container(classes=['contributors-grid'])
+            container.append(nodes.raw('', 
+                f'<style>.contributors-grid {{ display: grid; grid-template-columns: repeat({columns}, 1fr); gap: 20px; }}</style>', 
+                format='html'))
+            
+            # Add each contributor
+            for contributor in contributors[:max_contributors]:
+                login = contributor['login']
+                avatar_url = contributor['avatar_url']
+                profile_url = contributor['html_url']
+                contributions = contributor['contributions']
+                
+                # Create a container for this contributor
+                contributor_div = nodes.container(classes=['contributor'])
+                contributor_div.append(nodes.raw('', 
+                    f'''
+                    <div style="text-align: center; margin-bottom: 10px;">
+                        <a href="{profile_url}" target="_blank" style="text-decoration: none;">
+                            <img src="{avatar_url}" alt="{login}" style="width: 80px; height: 80px; border-radius: 50%; margin-bottom: 5px;" />
+                            <div>{login}</div>
+                            <div style="font-size: 0.8em; color: #666;">{contributions} commit{"s" if contributions != 1 else ""}</div>
+                        </a>
+                    </div>
+                    ''', 
+                    format='html'))
+                    
+                container.append(contributor_div)
+                
+            return [container]
+            
+        except Exception as e:
+            warning_node = nodes.warning()
+            warning_node += nodes.paragraph(text=f"Error getting GitHub contributors: {e}")
+            return [warning_node]
+
+
+def setup(app):
+    """
+    Set up the Sphinx extension.
+    """
+    app.add_directive('github-contributors', GithubContributorsDirective)
+    
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }