Enable custom href fragment for details directive (#30)

* add href option * change default title * changelog * documentation * documentation * fix * Apply suggestions from code review Co-authored-by: Josh Izaac <[email protected]> * example w/o href option * black * lint Co-authored-by: Josh Izaac <[email protected]>
XanaduAI · Nov 16, 2022 · d39592e · d39592e
1 parent 2cab406
commit d39592e
Show file tree

Hide file tree

Showing 3 changed files with 40 additions and 7 deletions.
diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md
@@ -5,11 +5,15 @@
 * Fixed an issue where footnote references were being rendered without brackets.
   [#25](https://github.com/XanaduAI/xanadu-sphinx-theme/pull/25)
 
+* Added the option to customize the href fragment of the details directive
+  [#26](https://github.com/XanaduAI/xanadu-sphinx-theme/pull/26)
+
 ### Contributors
 
 This release contains contributions from (in alphabetical order):
 
 [Josh Izaac](https://github.com/josh146).
+[David Wierichs](https://github.com/dwierichs).
 
 ## Release 0.3.2
 

diff --git a/doc/directives.rst b/doc/directives.rst
@@ -38,7 +38,8 @@ Details Dropdown
 .. code-block:: rest
 
     .. details::
-        :title: Usage Details
+        :title: Important Details
+        :href: important-details
 
         In general, the block takes D parameters and **must** have the following signature:
 
@@ -49,10 +50,22 @@ Details Dropdown
         For a block with multiple parameters, ``n_params_block`` is equal to the number of parameters in ``block``.
         For a block with a single parameter, ``n_params_block`` is equal to the length of the parameter array.
 
+    .. details::
+        :title: Usage Details
+
+        This function can be used with any of the supported autodifferentiation frameworks. It also supports
+        just-in-time compilation with JAX:
+
+        .. code-block:: python
+
+            jax.jit(unitary)(parameter1, parameter2, ... parameterD, wires)
+
+
 .. admonition:: Example:
 
     .. details::
-        :title: Usage Details
+        :title: Important Details
+        :href: important-details
 
         In general, the block takes D parameters and **must** have the following signature:
 
@@ -63,6 +76,16 @@ Details Dropdown
         For a block with multiple parameters, ``n_params_block`` is equal to the number of parameters in ``block``.
         For a block with a single parameter, ``n_params_block`` is equal to the length of the parameter array.
 
+    .. details::
+        :title: Usage Details
+
+        This function can be used with any of the supported autodifferentiation frameworks. It also supports
+        just-in-time compilation with JAX:
+
+        .. code-block:: python
+
+            jax.jit(unitary)(parameter1, parameter2, ... parameterD, wires)
+
 
 Gallery Item
 ------------

diff --git a/xanadu_sphinx_theme/directives/details.py b/xanadu_sphinx_theme/directives/details.py
@@ -12,15 +12,15 @@
         <a
           class="details-header collapse-header"
           data-toggle="collapse"
-          href="#details"
+          href="#{href}"
           aria-expanded="false"
           aria-controls="details"
         >
             <h2 style="font-size: 24px;">
                 <i class="fas fa-angle-down rotate" style="float: right;"></i> {title}
             </h2>
         </a>
-        <div class="collapse" id="details">
+        <div class="collapse" id="{href}">
 
     {content}
 
@@ -31,19 +31,25 @@
 )
 
 
+def lower_and_hyphenize(string):
+    """Turns a string into lower case and replaces spaces by hyphens."""
+    return string.lower().replace(" ", "-")
+
+
 class DetailsDirective(Directive):
     """Creates a collapsable Details section."""
 
     required_arguments = 0
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec = {"title": directives.unchanged}
+    option_spec = {"title": directives.unchanged, "href": lower_and_hyphenize}
     has_content = True
     add_index = False
 
     def run(self):
-        title = self.options.get("title", "Details and Conventions")
-        rst = TEMPLATE.format(title=title, content="\n".join(self.content))
+        title = self.options.get("title", "Usage Details")
+        href = self.options.get("href", lower_and_hyphenize(title))
+        rst = TEMPLATE.format(title=title, content="\n".join(self.content), href=href)
         string_list = StringList(rst.split("\n"))
         node = nodes.tbody()
         self.state.nested_parse(string_list, self.content_offset, node)