From af82d5eaeda02561b29adec38d40bf22c3a8e23b Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 29 Oct 2013 17:07:24 -0700 Subject: Made a sphinx extension which emits the hazardous materials danger admonition --- docs/conf.py | 6 +++- docs/cryptography-docs.py | 46 +++++++++++++++++++++++++ docs/hazmat/bindings/index.rst | 7 +--- docs/hazmat/bindings/openssl.rst | 7 +--- docs/hazmat/primitives/cryptographic-hashes.rst | 7 +--- docs/hazmat/primitives/hmac.rst | 7 +--- docs/hazmat/primitives/index.rst | 7 +--- docs/hazmat/primitives/padding.rst | 7 +--- docs/hazmat/primitives/symmetric-encryption.rst | 6 +--- 9 files changed, 58 insertions(+), 42 deletions(-) create mode 100644 docs/cryptography-docs.py (limited to 'docs') 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/cryptography-docs.py b/docs/cryptography-docs.py new file mode 100644 index 00000000..d6dc9d04 --- /dev/null +++ b/docs/cryptography-docs.py @@ -0,0 +1,46 @@ +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 -- cgit v1.2.3