Tell sphinx that the output depends on doxygen's documentation.

Tell sphinx that the output depends on the C/h files where the entities are defined.

This needs #5 to be useful.

Alternatively, depend on the XML files (but that would need an external method to check if the content changed, because Doxygen will always touch the files).

The current documentation states that:

The templating and XML handling logic is designed so that in the future it is possible to run the XSL transformation online, using generic tools. For this reason, there should not be any custom functions defined and no stylesheet parameters that depend on the plugin to set them.

Recent profiling has proven that XSLT processing comprises only a minor percentage of total time (in fact, after aa4525a most time is taken by the writing step.)

By abandoning the "offline" philosophy it will be possible to simplify code and enhance customizability:

• Add custom XSL function that can query the DoxyDB.
• Add template parameters that are supplied from the directive's parameters.

An obvious candidate is the :noindex: parameter, that is still unimplemented and would be trivial if XSL template parameters were allowed.

Going back to the above quote, the idea is already being betrayed in the XSL implementation. From the docs:

To apply the XSL transformation, the XML element corresponding to the entity being documented (e.g. a or a ) is extracted from its containing document and the transform is run as if that element was the root element. This means XPath expressions may give different results when the the same stylesheet is applied to a whole doxygen XML.

Hi @jcarrano,

I noticed this repo on a search I occasionally run for new code interacting with Doxygen's sqlite3 database. It didn't look like you're actually using it--just that you mention it?

In any case, I wanted to give you a heads up that I'm working on a pretty big update to Doxygen's sqlite3 generator. If I can get the contribution accepted, the schema (and quality of the data it holds) may change in a future Doxygen version.

Also, are you aware of Breathe (https://github.com/michaeljones/breathe)? At a glance, it sounds like you're both working to leverage Doxygen's output, via XML, to generate Sphinx documentation.

• Verify that it is a problem.
• use env-purge-doc

We need something to show off.

We can steal that from breathe.

Add at least basic support for the following entity types. Aesthetics can be solved later:

• class
• struct
• union
• define
• variable
• typedef
• enum
  • enumvalue
• function
• Aggregate Compounds
  • group
  • file

Low priority/extras:

• dir
• exception
• namespace
• page
• example

Plan A:

• Before the (possibly parallel) build starts: load Doxy DB in memory, dump it to string (iterdump), set the string as an attribute of the app.
• (Maybe this cannot be done) Mark the xml documents (maybe only index.xml) with note_dependency
• In the reading phase, read the load containing the DB into each worker. This is much faster than rereading all the xml documents, esp if parallel build is used.

A SQL command dump is smaller than a sqlite saved database (12M vs 7.5M for the RIOT docs).

Detect changed XML files and rebuild the database instead of reloading it from Sphinx's state.

Provide a means for smooth transition from doxygen html to sphinx.

Of course we can't expect people to write hundreds of rst documents at once, so there must be a way to have entities documented in sphinx without doing it manually.

Description

The setup should request sphinx<3 until this is fixed.

Error

Running Sphinx v3.1.0
making output directory... done
(Re-)Reading Doxygen DB
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 3 source files that are out of date
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [100%] xxxxxxx
Exception occurred:
  File "/home/jcarrano/.local/lib/python3.8/site-packages/sphinx/domains/c.py", line 3442, in clear_doc
    for fullname, (fn, _id, _l) in list(self.objects.items()):
ValueError: not enough values to unpack (expected 3, got 2)
The full traceback has been saved in /tmp/sphinx-err-n6iurq1w.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

If there is a file a/b.h and another one b.h, resolve_target() will raise AmbiguousTarget.

And make the build depend on that file.

It should be possible to import the default stylesheet. See https://lxml.de/resolvers.html#i-o-access-control-in-xslt for more info.

This is a documentation tool. It should have documentation!

Turn the README into a marketing/showoff pamphlet and move the real technical data into the manual.

Make an example doxygen project with an example sphinx project.

Maybe we can steal it from somewhere.

setup.py and all that stuff.

Use the gen_stubs.py script as an example.