[Bf-docboard-svn] bf-manual: [8199] trunk/blender_docs: Add custom reference directive

[Aaron Carlisle]

Revision: 8199
          https://developer.blender.org/rBM8199
Author:   Blendify
Date:     2021-07-12 04:23:25 +0200 (Mon, 12 Jul 2021)
Log Message:
-----------
Add custom reference directive

The goal of this change is to simplify our custom markup.

Instead of:

```
.. admonition:: Reference
   :class: refbox
```

Writers can now just use:

```
.. reference::
```

This is easier to type and remember and is less prone to errors.

Modified Paths:
--------------
    trunk/blender_docs/manual/conf.py

Added Paths:
-----------
    trunk/blender_docs/exts/reference.py

Added: trunk/blender_docs/exts/reference.py
===================================================================
--- trunk/blender_docs/exts/reference.py	                        (rev 0)
+++ trunk/blender_docs/exts/reference.py	2021-07-12 02:23:25 UTC (rev 8199)
@@ -0,0 +1,67 @@
+
+from docutils import nodes
+from docutils.nodes import Element, Node
+from docutils.parsers.rst import directives
+from docutils.parsers.rst.directives.admonitions import BaseAdmonition
+
+from sphinx.locale import _
+from sphinx.util.docutils import SphinxDirective
+from sphinx.util.typing import OptionSpec
+
+
+class refbox(nodes.Admonition, nodes.Element):
+    pass
+
+
+def visit_refbox_node(self, node):
+    self.visit_admonition(node)
+
+
+def depart_refbox_node(self, node):
+    self.depart_admonition(node)
+
+
+class ReferenceDirective(BaseAdmonition, SphinxDirective):
+    node_class = refbox
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec: OptionSpec = {
+        'class': directives.class_option,
+        'name': directives.unchanged,
+    }
+
+    def run(self):
+        if not self.options.get('class'):
+            self.options['class'] = ['refbox']
+
+        (reference,) = super().run()
+        if isinstance(reference, nodes.system_message):
+            return [reference]
+        elif isinstance(reference, refbox):
+            reference.insert(0, nodes.title(text=_('Reference')))
+            reference['docname'] = self.env.docname
+            self.add_name(reference)
+            self.set_source_info(reference)
+            self.state.document.note_explicit_target(reference)
+            return [reference]
+        else:
+            raise RuntimeError  # never reached here
+
+
+def setup(app):
+    app.add_node(refbox,
+                html=(visit_refbox_node, depart_refbox_node),
+                latex=(visit_refbox_node, depart_refbox_node),
+                text=(visit_refbox_node, depart_refbox_node),
+                man=(visit_refbox_node, depart_refbox_node),
+                texinfo=(visit_refbox_node, depart_refbox_node))
+
+    app.add_directive('reference', ReferenceDirective)
+
+    return {
+        'version': '1.0',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }


Property changes on: trunk/blender_docs/exts/reference.py
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
Modified: trunk/blender_docs/manual/conf.py
===================================================================
--- trunk/blender_docs/manual/conf.py	2021-07-12 02:14:09 UTC (rev 8198)
+++ trunk/blender_docs/manual/conf.py	2021-07-12 02:23:25 UTC (rev 8199)
@@ -50,6 +50,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'reference',
     'youtube',
     'vimeo',
     'sphinx.ext.mathjax',