Merge pull request #195 from alex/sphinx-hazmat-plugin

Sphinx hazmat plugin

10 files changed, 70 insertions, 46 deletions

diff --git a/docs/conf.py b/docs/conf.py
index a368ac70..8e0fc7be 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -11,10 +11,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import os
+import sys
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration ----------------------------------------------------
 
@@ -28,6 +31,7 @@ extensions = [
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
+    'cryptography-docs',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 6a76c705..e1475b88 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -117,10 +117,17 @@ Docstrings should be written like this:
 
 So, specifically:
 
-- Always use three double quotes.
-- Put the three double quotes on their own line.
-- No blank line at the end.
-- Use Sphinx parameter/attribute documentation `syntax`_.
+* Always use three double quotes.
+* Put the three double quotes on their own line.
+* No blank line at the end.
+* Use Sphinx parameter/attribute documentation `syntax`_.
+
+When documenting a new module in the ``hazmat`` package, its documentation
+should begin with the "Hazardous Materials" warning:
+
+.. code-block:: rest
+
+    .. hazmat::
 
 Development Environment
 -----------------------
diff --git a/docs/cryptography-docs.py b/docs/cryptography-docs.py
new file mode 100644
index 00000000..4ed5526a
--- /dev/null
+++ b/docs/cryptography-docs.py
@@ -0,0 +1,47 @@
+from docutils import nodes
+
+from sphinx.util.compat import Directive, make_admonition
+
+
+DANGER_MESSAGE = """
+This is a "Hazardous Materials" module. You should **ONLY** use it if you're
+100% absolutely sure that you know what you're doing because this module is
+full of land mines, dragons, and dinosaurs with laser guns. """
+
+
+class HazmatDirective(Directive):
+    def run(self):
+        ad = make_admonition(
+            Hazmat,
+            self.name,
+            [],
+            self.options,
+            nodes.paragraph("", DANGER_MESSAGE),
+            self.lineno,
+            self.content_offset,
+            self.block_text,
+            self.state,
+            self.state_machine
+        )
+        ad[0].line = self.lineno
+        return ad
+
+
+class Hazmat(nodes.Admonition, nodes.Element):
+    pass
+
+
+def visit_hazmat_node(self, node):
+    return self.visit_admonition(node, "danger")
+
+
+def depart_hazmat_node(self, node):
+    return self.depart_admonition(node)
+
+
+def setup(app):
+    app.add_node(
+        Hazmat,
+        html=(visit_hazmat_node, depart_hazmat_node)
+    )
+    app.add_directive("hazmat", HazmatDirective)
diff --git a/docs/hazmat/bindings/index.rst b/docs/hazmat/bindings/index.rst
index 4de2df47..19e03999 100644
--- a/docs/hazmat/bindings/index.rst
+++ b/docs/hazmat/bindings/index.rst
@@ -1,9 +1,4 @@
-.. danger::
-
-    This is a "Hazardous Materials" module. You should **ONLY** use it if
-    you're 100% absolutely sure that you know what you're doing because this
-    module is full of land mines, dragons, and dinosaurs with laser guns.
-
+.. hazmat::
 
 Bindings
 ========
diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst
index 00e8094a..194eeb92 100644
--- a/docs/hazmat/bindings/openssl.rst
+++ b/docs/hazmat/bindings/openssl.rst
@@ -1,9 +1,4 @@
-.. danger::
-
-    This is a "Hazardous Materials" module. You should **ONLY** use it if
-    you're 100% absolutely sure that you know what you're doing because this
-    module is full of land mines, dragons, and dinosaurs with laser guns.
-
+.. hazmat::
 
 OpenSSL
 =======
diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst
index 8f1d342f..c780dcb0 100644
--- a/docs/hazmat/primitives/cryptographic-hashes.rst
+++ b/docs/hazmat/primitives/cryptographic-hashes.rst
@@ -1,9 +1,4 @@
-.. danger::
-
-    This is a "Hazardous Materials" module. You should **ONLY** use it if
-    you're 100% absolutely sure that you know what you're doing because this
-    module is full of land mines, dragons, and dinosaurs with laser guns.
-
+.. hazmat::
 
 Message Digests
 ===============
diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst
index e66de36f..44cc29fa 100644
--- a/docs/hazmat/primitives/hmac.rst
+++ b/docs/hazmat/primitives/hmac.rst
@@ -1,9 +1,4 @@
-.. danger::
-
-    This is a "Hazardous Materials" module. You should **ONLY** use it if
-    you're 100% absolutely sure that you know what you're doing because this
-    module is full of land mines, dragons, and dinosaurs with laser guns.
-
+.. hazmat::
 
 Hash-based Message Authentication Codes
 =======================================
diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst
index ee1e251c..c81018ae 100644
--- a/docs/hazmat/primitives/index.rst
+++ b/docs/hazmat/primitives/index.rst
@@ -1,9 +1,4 @@
-.. danger::
-
-    This is a "Hazardous Materials" module. You should **ONLY** use it if
-    you're 100% absolutely sure that you know what you're doing because this
-    module is full of land mines, dragons, and dinosaurs with laser guns.
-
+.. hazmat::
 
 Primitives
 ==========
diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst
index ba3ddcc0..aebb4d4d 100644
--- a/docs/hazmat/primitives/padding.rst
+++ b/docs/hazmat/primitives/padding.rst
@@ -1,9 +1,4 @@
-.. danger::
-
-    This is a "Hazardous Materials" module. You should **ONLY** use it if
-    you're 100% absolutely sure that you know what you're doing because this
-    module is full of land mines, dragons, and dinosaurs with laser guns.
-
+.. hazmat::
 
 Padding
 =======
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 9a5bce07..1e047b7c 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -1,8 +1,4 @@
-.. danger::
-
-    This is a "Hazardous Materials" module. You should **ONLY** use it if
-    you're 100% absolutely sure that you know what you're doing because this
-    module is full of land mines, dragons, and dinosaurs with laser guns.
+.. hazmat::
 
 
 Symmetric Encryption