[doc] Implement ReST directive to include python package data file
authorSylvain Thénault <sylvain.thenault@logilab.fr>
Tue, 11 Apr 2017 15:45:35 +0200
changeset 272 625869ea6cf3
parent 271 a333022523cc
child 273 fb4e209dc50c
[doc] Implement ReST directive to include python package data file
MANIFEST.in
doc/rext.py
--- a/MANIFEST.in	Wed Apr 12 11:44:56 2017 +0200
+++ b/MANIFEST.in	Tue Apr 11 15:45:35 2017 +0200
@@ -3,7 +3,7 @@
 recursive-include cubicweb_sherpa/i18n *.po *.pot
 include cubicweb_sherpa/views/templates/*.html
 include tox.ini
-include doc/Makefile doc/conf.py doc/*.rst
+include doc/Makefile doc/*.py doc/*.rst
 include dev-requirements.txt
 include test/*.py test/data/bootstrap_cubes
 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/rext.py	Tue Apr 11 15:45:35 2017 +0200
@@ -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)