michaeljones/breathe — pull request #52 by scopatz (2012-12-01 05:39:54+00:00)
Title: autodoc-like directive for doxygenindex

First off, let me thank you @michaeljones (and others) for such an awesome project. This really is occupies that rare space of being super useful, quite beautiful, and very functional.

In any event, one thing that I noticed was missing from breathe was an autodoc-like directive. Specifically, there wasn't an automodule analogy. Since there didn't seem to be an issue related to adding this on the issue tracker I just went ahead and implemented it.

The new directive may be used as follows:
```rst
.. autodoxygenindex:: ../path/to/myfile.h
:project: myproj
```

This pull request only modifies the directives.py file and depends only on the standard library. This adds an AutoDoxygenIndexDirective class which subclasses from the DoxygenIndexDirective class. It adopts the strategy that the doxygen generated XML files are temporary. Thus the standard library ``tempfile`` module is used to create a new space for creating a cfg file, running doxygen, using breathe and sphinx to generate the actual documentation, and then finally cleaning up this temporary dir.

I have found that it works quite nicely and saves me a lot of manual effort. In theory, other autodoxygenXXX directives for the various doxygen directives. These would be simple enough to base off of AutoDoxygenIndexDirective. However, the only other one I can think that would really make sense for this would be doxygenfile.

As an added feature, the rst aliases are added automatically and so ``\rst`` and ``\endrst`` may be used in any autodoxygen'd file.

I hope you like it! Thanks again for the great project.