C[omp]ute

From: andrew cooke <andrew@...>

Date: Thu, 3 Aug 2017 20:03:04 -0400

Spent some time playing around with Doyxgen, Sphinx and Breathe.

The pipeline is:

  * Write docs in Doxygen as normal

  * Run Doxygen to generate xml output

  * Write Sphinx framework (mainly near-empty pages) that use 
    Breate, as a Sphinx plugin, to pull docs from Doxygen XML 
    (instead of from Python).

There's also a script that generates the PShinx outline
(breathe-apidoc.py), but it didn't seem to make much sense to me
(maybe I misunderstood).

Anyway, it's no good.  It almost works, but Breathe is buggy and
unsupported, so you end up with gaps (no structs...) and weird
inconsistencies.

I guess next I need to try improving Doxygen CSS.

Breathe:
https://breathe.readthedocs.io/en/latest
https://github.com/michaeljones/breathe

Andrew