feat: adding set custom var directive. Also functions to remove 'edit this page' and 'show source' buttons.

Author: germa89

doc/source/conf.py

@@ -3,11 +3,13 @@
 from datetime import datetime
 import os
 from pathlib import Path
+import sys
 from typing import List
 
 from github import Github
 import pyvista
 import requests
+import sphinx
 from sphinx.builders.latex import LaTeXBuilder
 
 from ansys_sphinx_theme import (
@@ -24,6 +26,9 @@
 THIS_PATH = Path(__file__).parent.resolve()
 EXAMPLE_PATH = (THIS_PATH / "examples" / "sphinx_examples").resolve()
 
+# To allow using 'helper' python file as a module
+sys.path.append(Path(__file__).parent)
+
 # Project information
 project = "ansys_sphinx_theme"
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
@@ -265,3 +270,126 @@ def download_and_process_files(example_links: List[str]) -> List[str]:
     },
     "pdf_guide": {"version": get_version_match(__version__)},  # noqa: E501
 }
+
+
+def remove_edit_this_page_if_directive(
+    app: sphinx.app,
+    pagename: str,
+    templatename: str,
+    context: sphinx.context,
+    doctree: sphinx.doctree,
+    page_vars: dict,
+):
+    """Remove 'edit this page' button.
+
+    Remove the 'edit this page' link in this page if the page variable
+    'hide_edit_page_button' is true.
+
+    Parameters
+    ----------
+    app : sphinx.app
+        Sphinx app
+    pagename : str
+        Page name
+    templatename : str
+        Template name
+    context : sphinx.context
+        Page context
+    doctree : sphinx.doctree
+        Page doctree
+    page_vars : dict
+        Page variables
+    """
+    # Remove the edit button for the index page
+    if "hide_edit_page_button" in page_vars:
+        if page_vars["hide_edit_page_button"].lower() == "true":
+            # breakpoint()
+            context.pop("theme_use_edit_page_button", False)
+
+
+def remove_show_source_if_directive(
+    app: sphinx.app,
+    pagename: str,
+    templatename: str,
+    context: sphinx.context,
+    doctree: sphinx.doctree,
+    page_vars: dict,
+):
+    """Remove the 'show_source' link.
+
+    Remove the 'show_source' link in this page if the page variable
+    'hide_show_source' is true.
+
+    Parameters
+    ----------
+    app : sphinx.app
+        Sphinx app
+    pagename : str
+        Page name
+    templatename : str
+        Template name
+    context : sphinx.context
+        Page context
+    doctree : sphinx.doctree
+        Page doctree
+    page_vars : dict
+        Page variables
+    """
+    # Remove the edit button for the index page
+    if "hide_show_source" in page_vars:
+        if page_vars["hide_show_source"].lower() == "true":
+            context["show_source"] = False
+
+
+def pre_build_page_html(
+    app: sphinx.app,
+    pagename: str,
+    templatename: str,
+    context: sphinx.context,
+    doctree: sphinx.doctree,
+):
+    """Apply hooks before building HTML.
+
+    Apply the hooks as functions before building the HTML files.
+
+    Parameters
+    ----------
+    app : sphinx.app
+        Sphinx app
+    pagename : str
+        Page name
+    templatename : str
+        Template name
+    context : sphinx.context
+        Page context
+    doctree : sphinx.doctree
+        Page doctree
+    """
+    from helpers import get_page_vars
+
+    page_vars = get_page_vars(app, pagename)
+
+    ## Hooks
+    remove_edit_this_page_if_directive(app, pagename, templatename, context, doctree, page_vars)
+
+    remove_show_source_if_directive(app, pagename, templatename, context, doctree, page_vars)
+
+
+def setup(app: sphinx):
+    """Add custom configuration to sphinx app.
+
+    Parameters
+    ----------
+    app : sphinx.application.sphinx
+        The Sphinx application.
+    """
+    from helpers import SetPageVariableDirective, add_custom_variables_to_context
+
+    # Register the directive
+    app.add_directive("setpagevar", SetPageVariableDirective)
+
+    # Hook into the html-page-context event
+    app.connect("html-page-context", add_custom_variables_to_context)
+
+    # setting pre-build functions
+    app.connect("html-page-context", pre_build_page_html)

doc/source/helpers.py

@@ -0,0 +1,109 @@
+"""Helper classes and functions for documentation build."""
+
+from docutils.parsers.rst import Directive
+import sphinx
+
+
+def get_page_vars(app: sphinx.app, pagename: str) -> dict:
+    """Get page variables.
+
+    Get each page variables.
+
+    Parameters
+    ----------
+    app : app
+        Sphinx app
+    pagename : str
+        Page name
+
+    Returns
+    -------
+    dict
+        Dictionary with variables as keys, and their values.
+    """
+    env = app.builder.env
+
+    if (
+        not hasattr(env, "pages_vars")
+        or not env.pages_vars
+        or not env.pages_vars.get(pagename, None)
+    ):
+        return
+
+    return env.pages_vars[pagename]
+
+
+class SetPageVariableDirective(Directive):
+    """Set page variables.
+
+    Set page variables.
+
+    Parameters
+    ----------
+    - variable: str
+    - value: str
+
+    Example
+
+    .. setpagevar:: my_key my_value
+
+    The key cannot have spaces.
+
+    .. setpagevar:: my_key my value
+
+    """
+
+    has_content = False
+    required_arguments = 2  # Variable name and value
+    optional_arguments = 0
+
+    def run(self):
+        """Run directive."""
+        var_name = self.arguments[0]
+        var_value = self.arguments[1]
+        env = self.state.document.settings.env
+
+        # Store the variable in the environment specific to each page
+        if not hasattr(env, "pages_vars"):
+            env.pages_vars = {}
+
+        # Store the variable for the current page (env.docname is the document name)
+        if env.docname not in env.pages_vars:
+            env.pages_vars[env.docname] = {}
+
+        env.pages_vars[env.docname][var_name] = var_value
+
+        return []
+
+
+def add_custom_variables_to_context(
+    app: sphinx.app,
+    pagename: str,
+    templatename: str,
+    context: sphinx.context,
+    doctree: sphinx.doctree,
+) -> None:
+    """Add customs variables to build context.
+
+    This is needed to be able to access the vars at the build stage.
+
+    Parameters
+    ----------
+    app : Sphinx.app
+        Sphinx app.
+    pagename : str
+        Page name
+    templatename : str
+        Template page
+    context : Sphinx.context
+        Page context
+    doctree : Sphinx.doctree
+        Page doctree
+    """
+    env = app.builder.env
+
+    # Check if there are page-specific variables stored by the directive
+    if hasattr(env, "pages_vars"):
+        if pagename in env.pages_vars:
+            # Add the stored variables to the context for this page
+            context.update(env.pages_vars[pagename])