On Thu, Jul 8, 2010 at 8:02 AM, Matt Williams <[email protected]> wrote:
> Hi all, > > I've recently discovered Sphinx and have decided to start using it for > a number of my C++ library projects for end-user documentation. For > these projects I'm using Doxygen to create HTML API docs covering the > whole library. I'm keeping this bit Doxygen-based since it does the > job so well. However, from within my Sphinx docs, I'm wanting to link > (as in hyperlink) to classes or methods in the Doxygen API docs so > that the user can read more detailed information about the > methods/classes. > > In search of this integration I came across Breathe [1] which instead > of simply linking, extracts the information from the XML files and > implants it into Sphinx directly. A very cool idea which I'm sure I > will use at some point but not quite what I want. I realised that what > I really wanted was a customisation of the extlinks extension but with > a bit more logic which would search thorough a Doxygen 'tag' file and > extract the URLs. > > To this end I decided to bite the bullet and write a Sphinx extension > myself. Using the extlinks extension as reference and reading the > documentation I quickly had a working prototype so good work on the > simply API and decent documentation (though I may be submitting some > patches for expanding on part of the documentation). I've attached my > version so far and I would appreciate comments about it. I'm sure > there's things I'm doing in a very strange way :) > > One of the biggest problems I've had is working out what node type (as > in docutils.nodes) to use in what case. For example, in my extension, > if the C++ symbol matches one in the Doxygen tag file then the role > returns a docutils.nodes.reference. However, if the symbol isn't found > then I want to be able to just return a plain text node (i.e. with no > <a href=""> in HTML mode). Nowhere can I seem to find a list of the > nodes, what they're used for and a simple description of their > signatures/usage. > > Good work on Sphinx so far everyone, it's a great tool and very easily > extensible. > > Cheers, > Matt Williams > > [1] http://github.com/michaeljones/breathe > > You might also be interested in looking at some of the other extensions that do external linking from sphinx. I recently put a "traclinks" extension [1] in the sphinx-contrib repo. I've also created an extension which creates links to pydoctor documentation, which I'll be publishing to the sphinx-contrib repo soon, but haven't yet. You can find it in the lore2sphinx repo [2] for the moment, though it's called "apilinks" there. In any case, I hope when you have your extension polished up, you'll consider publishing it to the sphinx-contrib repo (or somewhere else) for others to benefit from. And I totally agree that a list of docutils node types would be crazy-useful. I've also been looking for something like that for a while. [1] http://bitbucket.org/birkenfeld/sphinx-contrib/ [2] http://bitbucket.org/khorn/lore2sphinx -- You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
