breathe

History

Brendan caba061910 documentation overhaul (#816 ) * Fix all warnings in docs build By adjusting either the restructured text or code/doxygen setup as needed. Including some renaming of C/C++ symbols for uniqueness so that we don't have duplicate IDs throughout the docs. Other parts use no-link to avoid generating unused or duplicate IDs. Some other parts are commented out in the restructured text so that we don't render them any more. For example, the mux vdhl stuff in the doxygen test suite. We've include the lists of warnings that doxygen generates but we can get rid of those at some point. * Pin docs CI (& RTD) to use doxygen 1.9.3 - tell sphinx to treat warnings as errors (replacing nit-picky mode) - fix awkward word choice in a a doc - RTD will use conda forge to get updated docygen executable. GH CI will get doxygen from SourceForge archives binary executable - document the entire namespace instead individual members of the typeedf example test - use a different member as the `extern` member test (for reason related to undefined types in member's parameters) - define empty structures to use as a reference for a type in a parameter/return value of a documented function - add comments to explain what the empty structures are for - remove unnecessary inheritence from "image" example test * Upload xml artifacts with built docs * Adjust restructured text usage & formatting We use explicitly language-typed code blocks much more than before to have better syntax highlighting. We use links where possible instead of plain text references to directives and config variables. We reformat re-indent some of the text blocks as needed. * Fix link And further formatting tweaks. * Remove comments with undocumented entries We don't need a record of them. * Completely remove mux/vhdl examples If we're not supporting it (and we probably shouldn't) then there is no need to keep it around in the repository. * Remove duplicate specific examples If there appear elsewhere in the docs then that is all that matters. We don't need to keep commented out content about them. * Revert some `:` changes Also removed some trailing whitespace. Force Doxyfile snippets to be un-highlighted by pygments (which tends to assume its python syntax). * missed a colon in index.rst Co-authored-by: Michael Jones <m.pricejones@gmail.com> * Add ':' to union.rst file * temporarily keep RTD pinned to doxygen 1.9.2 This is done because of a problem with `\dotfile` in doxygen 1.9.3 * make dotfile test compatible with doxygen 1.9.3 If DOTFILE_DIRS tag is specified, then doxygen 1.9.3 will copy the dot file into the XML output folder and use a relative path when specifying the dotfile's name in XML. Breathe expects the dotfile to be specified using a absolute path (and filename) as that was the default behavior in 1.9.2 or prior. TL;DR: don't specify the DOTFILE_DIRS tag in the doxyfile config! Currently, there is no plan to workaround using DOTFILE_DIRS tag. * suppress doxygen warnings for dotfile test I'm painfully aware * pin CI workflow & RTD to use doxygen v1.9.3 * use env var directly (not from CI runner context) * Fix all warnings in docs build By adjusting either the restructured text or code/doxygen setup as needed. Including some renaming of C/C++ symbols for uniqueness so that we don't have duplicate IDs throughout the docs. Other parts use no-link to avoid generating unused or duplicate IDs. Some other parts are commented out in the restructured text so that we don't render them any more. For example, the mux vdhl stuff in the doxygen test suite. We've include the lists of warnings that doxygen generates but we can get rid of those at some point. * Pin docs CI (& RTD) to use doxygen 1.9.3 - tell sphinx to treat warnings as errors (replacing nit-picky mode) - fix awkward word choice in a a doc - RTD will use conda forge to get updated docygen executable. GH CI will get doxygen from SourceForge archives binary executable - document the entire namespace instead individual members of the typeedf example test - use a different member as the `extern` member test (for reason related to undefined types in member's parameters) - define empty structures to use as a reference for a type in a parameter/return value of a documented function - add comments to explain what the empty structures are for - remove unnecessary inheritence from "image" example test * Upload xml artifacts with built docs * Adjust restructured text usage & formatting We use explicitly language-typed code blocks much more than before to have better syntax highlighting. We use links where possible instead of plain text references to directives and config variables. We reformat re-indent some of the text blocks as needed. * Fix link And further formatting tweaks. * Remove comments with undocumented entries We don't need a record of them. * Completely remove mux/vhdl examples If we're not supporting it (and we probably shouldn't) then there is no need to keep it around in the repository. * Remove duplicate specific examples If there appear elsewhere in the docs then that is all that matters. We don't need to keep commented out content about them. * Revert some `:` changes Also removed some trailing whitespace. Force Doxyfile snippets to be un-highlighted by pygments (which tends to assume its python syntax). * missed a colon in index.rst Co-authored-by: Michael Jones <m.pricejones@gmail.com> * Add ':' to union.rst file * temporarily keep RTD pinned to doxygen 1.9.2 This is done because of a problem with `\dotfile` in doxygen 1.9.3 * make dotfile test compatible with doxygen 1.9.3 If DOTFILE_DIRS tag is specified, then doxygen 1.9.3 will copy the dot file into the XML output folder and use a relative path when specifying the dotfile's name in XML. Breathe expects the dotfile to be specified using a absolute path (and filename) as that was the default behavior in 1.9.2 or prior. TL;DR: don't specify the DOTFILE_DIRS tag in the doxyfile config! Currently, there is no plan to workaround using DOTFILE_DIRS tag. * suppress doxygen warnings for dotfile test I'm painfully aware * pin CI workflow & RTD to use doxygen v1.9.3 * use env var directly (not from CI runner context) * allow docs to use older doxygen Specifically for building breathe's docs. This is made possible by using the RST `ifconfig` directive. See #811 * ran black on conf.py * simple review changes * reverting NS directive changes Per request, most of the namespaced member changes are reverted. Also reverted temporary changes to dot_graphs.cfg project as the fix was merged into master (which this branch should now be based on). Some changes seemed to have been lost since I did a `git reset --hard origin/branch-name` I have restored what I noticed, but there may be some other changes that were lost. * revert another namespace related change reverted another namespace change in domains.rst * remove documented return values for void functions * revert other changes related to `-n` warnings * revert moving `f0` funcs in specific test sections * update mathjax_path to latest mathjax output was currently broken due to changes in mathjax distribution path/URL. Updating to latest restores proper output. * revert C array as requested (& hope for the best) Maybe the error about the `.. c:function::` signature is specific to my setup. * improve version check for doxygen & C++ concepts * Fix all warnings in docs build By adjusting either the restructured text or code/doxygen setup as needed. Including some renaming of C/C++ symbols for uniqueness so that we don't have duplicate IDs throughout the docs. Other parts use no-link to avoid generating unused or duplicate IDs. Some other parts are commented out in the restructured text so that we don't render them any more. For example, the mux vdhl stuff in the doxygen test suite. We've include the lists of warnings that doxygen generates but we can get rid of those at some point. * Pin docs CI (& RTD) to use doxygen 1.9.3 - tell sphinx to treat warnings as errors (replacing nit-picky mode) - fix awkward word choice in a a doc - RTD will use conda forge to get updated docygen executable. GH CI will get doxygen from SourceForge archives binary executable - document the entire namespace instead individual members of the typeedf example test - use a different member as the `extern` member test (for reason related to undefined types in member's parameters) - define empty structures to use as a reference for a type in a parameter/return value of a documented function - add comments to explain what the empty structures are for - remove unnecessary inheritence from "image" example test * Upload xml artifacts with built docs * Adjust restructured text usage & formatting We use explicitly language-typed code blocks much more than before to have better syntax highlighting. We use links where possible instead of plain text references to directives and config variables. We reformat re-indent some of the text blocks as needed. * Fix link And further formatting tweaks. * Remove comments with undocumented entries We don't need a record of them. * Completely remove mux/vhdl examples If we're not supporting it (and we probably shouldn't) then there is no need to keep it around in the repository. * Remove duplicate specific examples If there appear elsewhere in the docs then that is all that matters. We don't need to keep commented out content about them. * Revert some `:` changes Also removed some trailing whitespace. Force Doxyfile snippets to be un-highlighted by pygments (which tends to assume its python syntax). * missed a colon in index.rst Co-authored-by: Michael Jones <m.pricejones@gmail.com> * Add ':' to union.rst file * temporarily keep RTD pinned to doxygen 1.9.2 This is done because of a problem with `\dotfile` in doxygen 1.9.3 * make dotfile test compatible with doxygen 1.9.3 If DOTFILE_DIRS tag is specified, then doxygen 1.9.3 will copy the dot file into the XML output folder and use a relative path when specifying the dotfile's name in XML. Breathe expects the dotfile to be specified using a absolute path (and filename) as that was the default behavior in 1.9.2 or prior. TL;DR: don't specify the DOTFILE_DIRS tag in the doxyfile config! Currently, there is no plan to workaround using DOTFILE_DIRS tag. * suppress doxygen warnings for dotfile test I'm painfully aware * pin CI workflow & RTD to use doxygen v1.9.3 * use env var directly (not from CI runner context) * Fix all warnings in docs build By adjusting either the restructured text or code/doxygen setup as needed. Including some renaming of C/C++ symbols for uniqueness so that we don't have duplicate IDs throughout the docs. Other parts use no-link to avoid generating unused or duplicate IDs. Some other parts are commented out in the restructured text so that we don't render them any more. For example, the mux vdhl stuff in the doxygen test suite. We've include the lists of warnings that doxygen generates but we can get rid of those at some point. * Pin docs CI (& RTD) to use doxygen 1.9.3 - tell sphinx to treat warnings as errors (replacing nit-picky mode) - fix awkward word choice in a a doc - RTD will use conda forge to get updated docygen executable. GH CI will get doxygen from SourceForge archives binary executable - document the entire namespace instead individual members of the typeedf example test - use a different member as the `extern` member test (for reason related to undefined types in member's parameters) - define empty structures to use as a reference for a type in a parameter/return value of a documented function - add comments to explain what the empty structures are for - remove unnecessary inheritence from "image" example test * Adjust restructured text usage & formatting We use explicitly language-typed code blocks much more than before to have better syntax highlighting. We use links where possible instead of plain text references to directives and config variables. We reformat re-indent some of the text blocks as needed. * Completely remove mux/vhdl examples If we're not supporting it (and we probably shouldn't) then there is no need to keep it around in the repository. * Revert some `:` changes Also removed some trailing whitespace. Force Doxyfile snippets to be un-highlighted by pygments (which tends to assume its python syntax). * temporarily keep RTD pinned to doxygen 1.9.2 This is done because of a problem with `\dotfile` in doxygen 1.9.3 * make dotfile test compatible with doxygen 1.9.3 If DOTFILE_DIRS tag is specified, then doxygen 1.9.3 will copy the dot file into the XML output folder and use a relative path when specifying the dotfile's name in XML. Breathe expects the dotfile to be specified using a absolute path (and filename) as that was the default behavior in 1.9.2 or prior. TL;DR: don't specify the DOTFILE_DIRS tag in the doxyfile config! Currently, there is no plan to workaround using DOTFILE_DIRS tag. * pin CI workflow & RTD to use doxygen v1.9.3 * allow docs to use older doxygen Specifically for building breathe's docs. This is made possible by using the RST `ifconfig` directive. See #811 * ran black on conf.py * simple review changes * reverting NS directive changes Per request, most of the namespaced member changes are reverted. Also reverted temporary changes to dot_graphs.cfg project as the fix was merged into master (which this branch should now be based on). Some changes seemed to have been lost since I did a `git reset --hard origin/branch-name` I have restored what I noticed, but there may be some other changes that were lost. * revert another namespace related change reverted another namespace change in domains.rst * remove documented return values for void functions * revert other changes related to `-n` warnings * revert moving `f0` funcs in specific test sections * update mathjax_path to latest mathjax output was currently broken due to changes in mathjax distribution path/URL. Updating to latest restores proper output. * revert C array as requested (& hope for the best) Maybe the error about the `.. c:function::` signature is specific to my setup. * improve version check for doxygen & C++ concepts * ignore edge case * let RTD use the latest doxygen * final self-review * found a silent error in the doxygen test pg Co-authored-by: Michael Jones <m.pricejones@gmail.com>		2 months ago
..
doxygen	documentation overhaul (#816 )	2 months ago
specific	documentation overhaul (#816 )	2 months ago
tinyxml	documentation overhaul (#816 )	2 months ago