Merge pull request #195 from alex/sphinx-hazmat-plugin
Sphinx hazmat plugin
diff --git a/docs/conf.py b/docs/conf.py
index a368ac7..8e0fc7b 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 @@
'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 6a76c70..e1475b8 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -117,10 +117,17 @@
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 0000000..4ed5526
--- /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 4de2df4..19e0399 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 00e8094..194eeb9 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 8f1d342..c780dcb 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 e66de36..44cc29f 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 ee1e251..c81018a 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 ba3ddcc..aebb4d4 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 9a5bce0..1e047b7 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