[PATCH 7 of 9 saem_ref V2] [doc] Implement a pkg-resources-include directive for ReST

Sylvain Thenault sylvain.thenault at logilab.fr
Tue Apr 11 15:15:16 CEST 2017


# HG changeset patch
# User Sylvain Thénault <sylvain.thenault at logilab.fr>
# Date 1491911926 -7200
#      Tue Apr 11 13:58:46 2017 +0200
# Node ID 04d82e8990d0df261fdebaab341726fe6c006a6e
# Parent  7201b028314245fa185adabd0ce41a8a823dbe31
[doc] Implement a pkg-resources-include directive for ReST

diff --git a/doc/conf.py b/doc/conf.py
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -10,17 +10,19 @@
 # autogenerated file.
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import os
 import sys
-import os
 
 # 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('.'))
+
+import rext  # noqa
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
diff --git a/doc/rext.py b/doc/rext.py
new file mode 100644
--- /dev/null
+++ b/doc/rext.py
@@ -0,0 +1,34 @@
+"""ReST extensions"""
+
+from pkg_resources import Requirement, resource_filename, resource_exists
+
+from docutils.parsers.rst.directives import misc, register_directive
+
+
+class PkgResourcesInclude(misc.Include):
+    """Implement the `pkg-resources-include` directive, similar to the `include`
+    directive but taking a pypi project name as first argument and a data file
+    within the package as second argument.
+
+    Actual file location will be computed using pkg_resources facilities.
+
+    Example:
+
+        .. pkg-resources-include:: cubicweb-seda doc/profils.rst
+
+    """
+
+    required_arguments = 2
+
+    def run(self):
+        project, fpath = self.arguments
+
+        if not resource_exists(Requirement.parse(project), fpath):
+            raise Exception('Resource %s not found in %s' % (fpath, project))
+
+        filename = resource_filename(Requirement.parse(project), fpath)
+        self.arguments = [filename]
+        return super(PkgResourcesInclude, self).run()
+
+
+register_directive('pkg-resources-include', PkgResourcesInclude)


More information about the saem-devel mailing list