Investigate incremental building

[svenevs]

• Provide better documentation on how to make development easier. As mentioned in do not regenerate every file each time #140 (comment) the best way to temporarily disable the generated API / rebuilds from exhale is to comment out exhale and breathe from your conf.py extensions list. This prevents everything being redocumented.
• Support only regenerating documents that have changed (do not regenerate every file each time #140). May cause hidden no-rebuild but should have issues.
• Harder.
  • Detecting changes in doxygen input. Can you use the cache from breathe? You want to avoid duplicating their cache.
  • Need to get a better understanding of incremental builds with doxygen on its own.
  • Relates: slowness breathe-doc/breathe#439
    • Forcing this document to be reprocessed by sphinx pending do not regenerate every file each time #140 resolution.
  • Detecting files that were generated in a previous run, but changes in doxygen configs have now made it irrelevant.
  • If containmentFolder already exists, gather a list of all documents there (orig_files).
  • Generate all documents, accumulating a list of filenames that were generated (or skipped because they would be the same) (gen_files).
  • Delete any files from orig_files not found in gen_files.
  • Harder to create a test for for internal complications.

Note: progress on this is unlikely, thoughts welcome but incremental builds in this regime are complex and quite honestly intimidating. One of many reasons exhale is not well suited for large projects at this time.

[pczerkas]

How about comparing resulting files mtime to doxygen's index.xml file mtime?

[svenevs]

Unfortunately index.xml is overwritten every time, regardless of whether or not anything has changed. I won't have time to work on this for a while, but the plan is to md5 the file and the would-be contents and only write if they are the same. That'll at least be faster than doing a full string comparison, but I'll have to rewrite things to use StringIO for the node writing before opening the file.

Breathe also has its own internal cache though, so I'm going to have to take a closer look at how they did that and see if I can just use that directly.