[feature] Unified docs building for legacy code

jsturdy commented 4 years ago

Description

Uniform building of docs for legacy code:

on demand creation of conda environment for python deps and doxyrest (if specified)
- USE_CONDA and USE_DOXYREST can be set at docs building time to flag these behaviours
- if USE_CONDA is not set, the environment from which make doc is called needs all dependencies installed
split source and build directories for sphinx
use breathe+exhale for default C/C++ docs, with option to use doxyrest
- also retained previous manual breathe output

Types of changes

[x] New feature (non-breaking change which adds functionality)

Motivation and Context

Requests for documentation of legacy code

How Has This Been Tested?

https://test-gemdaq-ci.web.cern.ch/test-gemdaq-ci/docs/api/ctp7_modules/latest/

mexanick commented 4 years ago

At the moment the API documentation is generated in alphabetical order. I believe it would be much better if it would be split by module. Also, the markdown from README.md is not rendered correctly at code snippets.

jsturdy commented 4 years ago

At the moment the API documentation is generated in alphabetical order. I believe it would be much better if it would be split by module. Also, the markdown from README.md is not rendered correctly at code snippets.

Not sure why not, but the exhale API wasn't included here (check out the generated docs for xhal for an example of what that looks like), so I'll try to update that. I think the two tools do different things well, and neither of them do everything perfectly, but both of them limit the amount of manual work to prepare API documentation and someone could probably work with either to get some customization done. They were included in all repositories (with doxygen comments) to allow for easy visualization of the available options such that an informed choice could be made.

Also, not sure what's up with the README.md rendering... how good is markdown support in doxygen 1.8.5?

jsturdy commented 4 years ago

Also, not sure what's up with the README.md rendering... how good is markdown support in doxygen 1.8.5?

Actually, now I notice in the log:

WARNING: Pygments lexer name u'markdown' is not known

So it appears that there's a non automatic dependency on pygments-markdown-lexer, which pulls in Pygments>=2.0, and doing this seems to fix the issue

There are also some unescaped % symbols in the doxygen comments, which trips up the latex engine, so I've fixed those as well (seems to render fine)

jsturdy commented 4 years ago

Also, not sure what's up with the README.md rendering... how good is markdown support in doxygen 1.8.5?

Actually, now I notice in the log:
WARNING: Pygments lexer name u'markdown' is not known
So it appears that there's a non automatic dependency on pygments-markdown-lexer, which pulls in Pygments>=2.0, and doing this seems to fix the issue

Well, this may have been a red herring, as it built fine on my laptop (doxygen version 1.8.17) but still failed on gem904daq02 (doxygen version 1.8.5). I added installation of doxygen to the USE_CONDA option, which will pull doxygen version 1.8.18 into the conda environment, and this seems to be working fine (docs site is currently previewing that build)

jsturdy commented 4 years ago

last changes I think have been pushed.
docs site updated

cms-gem-daq-project / ctp7_modules