feat: adding custom vars directives

doc/changelog.d/523.added.md

@@ -0,0 +1 @@
+feat: adding custon vars directives

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])

doc/source/index.rst

@@ -8,6 +8,11 @@ This theme is specifically tailored for documentation related to Ansys projects
 helping to ensure consistency in its look and feel. Various useful extensions
 are included in the theme to make documentation more appealing and user-friendly.
 
+
+.. setpagevar:: hide_edit_page_button True
+
+.. setpagevar:: hide_show_source True
+
 .. grid:: 2
     :gutter: 2 2 3 4