Inclusion of external documentation in the Sphinx project

Question

We save quite a lot of documentation using Sphinx in SVN.

As part of the generated output, we would like to include release notes for Python related modules as main content (and not as a hyperlink!). Release Notes for external modules are also supported in SVN. Is there any way of the sphinxes to pull pieces of documentation from other sources (SVN)? Well, using external SVNs is a way to solve the problem, but maybe not the smartest way ... any better options?

Answer 1

Two possible options:

• Add the svn:externals link to the remote project (which you already know about).
• Extend Sphinx with a special directive to include files from remote subversion repositories.

I'm not an expert in Sphinx, but I was able to build a quick extension that embeds files from a remote disruptive repository.

The extension adds the svninclude directive, which takes 1 argument, the URL of the repository where your documents are located. He checks this repository for the temporary _svncache directory located in the root of the project, and then proceeds to read the contents of each file and inserts it into the parser state machine.

Here is the svninclude.py extension svninclude.py . It is simplified and does not currently check for errors. If you plan to implement this, let me know and I can give some additional tips if you are stuck:

 import os, re, subprocess, sys from docutils import nodes, statemachine from docutils.parsers.rst import directives from sphinx.util.compat import Directive, directive_dwim class SvnInclude(Directive): has_content = True required_arguments = 1 optional_arguments = 0 final_argument_whitespace = False def _setup_repo(self, repo): env = self.state.document.settings.env path = os.path.normpath(env.doc2path(env.docname, base=None)) cache = os.path.join(os.path.dirname(path), '_svncache') root = os.path.join(cache, re.sub('[\W\-]+', '_', repo)) if not os.path.exists(root): os.makedirs(root) subprocess.call(['svn', 'co', repo, root]) return root def run(self): root = self._setup_repo(self.arguments[0]) for path in self.content: data = open(os.path.join(root, path), 'rb').read() lines = statemachine.string2lines(data) self.state_machine.insert_input(lines, path) return [] def setup(app): app.add_directive('svninclude', directive_dwim(SvnInclude)) 

Here is an example of the markup you would include in your index.rst (or other file):

 .. svninclude:: http://svn.domain.com/svn/project one.rst doc/two.rst 

If the paths one.rst and doc/two.rst refer to the subversion URL, for example http://svn.domain.com/svn/project/one.rst .

You of course want to pack svninclude.py and install it in your Python path. Here is what I did to check this out:

• Added 'svninclude' to the extensions list in source/conf.py
• Posted by svninclude.py in the root of the project.

Then executed:

 % PYTHONPATH=. sphinx-build -b html ./source ./build