- add logo for branding in favicon and nav menu title
- remove all `.. contents::` directives as they're redundant in the furo theme (ToC has an independent menu)
- uniform some theme elements' colors (via custom CSS) to match the blue in breathe-doc.org
* 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>
When building an include for a non-referenced include entry, the
`nodes.Text` field is created with the node's `data` value empty and the
(deprecated) raw-source field to the desired include name. This causes
includes to render an "empty" include in the final Sphinx documentation.
This commit adjusts the building of the docutil's Text node to populate
the `data` option instead [1].
[1]: https://repo.or.cz/docutils.git/blob/d169015ee0f412cffd69b33654d8a119d99bc0f3:/docutils/nodes.py#l408
Signed-off-by: James Knight <james.d.knight@live.com>
Use users' input as root path component if breathe_projects (in conf.py) specifies an absolute path for the project's XML_OUTPUT (not recommended for hosting from a web server).
Otherwise, concatenate the path to conf.py with subsequent relative paths to the dot file (resulting in a clean absolute path).
Add generated dotfile.dot to gitignore since doxygen 1.9.3 copies the dotfile(s) to XML_OUTPUT
Considering the path to conf.py, make a dot file's relative path absolute using the project's XML_OUTPUT.
- add a module level docstr to describe the purpose of filetypes.py
- add types-Pygments to dev reqs
- adjust imports in filetypes.py to better suite the types-Pygments stubs.
Jakob Lykke Andersen