Fix various documentation issues#2844
Merged
Merged
Conversation
Prefer linking to sections rather than specific files, as these have changed a fair bit
We might want some check that `BoutReal == PetscScalar` but this type alias would just cover up any problem. At best, this wouldn't compile, but it's possible it would just lead to link time problems
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Fixes formatting of example, and ensures file docstring doesn't get attached to the `bout` namespace and so appear in every single file that has the namespace!
Member
Author
|
I've discovered that the vast majority of the warnings emitted from Sphinx are due to two separate bugs in doxygen and breathe. Things that still need doing:
|
include/bout/generic_factory.hxx is licensed under the MIT License based on Modern C++ Design/Loki by A. Alexandrescu
Update + add License for #2844 Fix various documentation issues
This reverts commit e6bc5c5. The commit tried to make boutuitls and boutdata non-importable for the documentation tool. If those modules should be remove from the documentation, this can be achieved by removing them from manual/sphinx/_apidoc/. This should not break the documentation fro boutpp or boutconfig.
Revert "Docs: Don't include boutdata/boututils in docs"
* next: (481 commits) CI: Show more output of dnf5 to help debugging CI: Disable annotations for clang-tidy-review CI: Bump clang-tidy-review Remove coverage test from github workflow CMake: Ensure we find ADIOS2 if we downloaded it Use modern `output` API Remove unused header include Remove unused `x_outer_dirichlet` member from LaplaceXY2 hypre Change test hypre type to `gmres` Fix laplacexy2-hypre test failing silently CMake: Bump downloaded SUNDIALS version CMake: Reduce duplication in linking against adios2 CMake: Ensure we find adios2 when linking against BOUT++ Apply clang-format changes hypre_interface: Add print() method to HypreMatrix tests/integrated: Fix hypre tests OptionsNetCDF: verifyTimesteps, write override base class Testing: Missed 3D + hypre combination Disable hypre with 3D metrics Prefer scientific notation ...
| }; | ||
|
|
||
| static std::mt19937 clock_gen(std::random_device{}()); | ||
| static std::mt19937 clock_gen{std::random_device{}()}; |
Contributor
There was a problem hiding this comment.
warning: variable 'clock_gen' is non-const and globally accessible, consider making it const [cppcoreguidelines-avoid-non-const-global-variables]
static std::mt19937 clock_gen{std::random_device{}()};
^Fix docs warnings update
| /// This should accept up to ten arguments | ||
| #define SOLVE_FOR(...) \ | ||
| { MACRO_FOR_EACH(SOLVE_FOR1, __VA_ARGS__) } | ||
| #define SOLVE_FOR(...) {MACRO_FOR_EACH(SOLVE_FOR1, __VA_ARGS__)} |
Contributor
There was a problem hiding this comment.
warning: variadic macro 'SOLVE_FOR' used; consider using a 'constexpr' variadic template function [cppcoreguidelines-macro-usage]
#define SOLVE_FOR(...) {MACRO_FOR_EACH(SOLVE_FOR1, __VA_ARGS__)}
^|
|
||
| #define SAVE_ONCE(...) \ | ||
| { MACRO_FOR_EACH(SAVE_ONCE1, __VA_ARGS__) } | ||
| #define SAVE_ONCE(...) {MACRO_FOR_EACH(SAVE_ONCE1, __VA_ARGS__)} |
Contributor
There was a problem hiding this comment.
warning: variadic macro 'SAVE_ONCE' used; consider using a 'constexpr' variadic template function [cppcoreguidelines-macro-usage]
#define SAVE_ONCE(...) {MACRO_FOR_EACH(SAVE_ONCE1, __VA_ARGS__)}
^|
|
||
| #define SAVE_REPEAT(...) \ | ||
| { MACRO_FOR_EACH(SAVE_REPEAT1, __VA_ARGS__) } | ||
| #define SAVE_REPEAT(...) {MACRO_FOR_EACH(SAVE_REPEAT1, __VA_ARGS__)} |
Contributor
There was a problem hiding this comment.
warning: variadic macro 'SAVE_REPEAT' used; consider using a 'constexpr' variadic template function [cppcoreguidelines-macro-usage]
#define SAVE_REPEAT(...) {MACRO_FOR_EACH(SAVE_REPEAT1, __VA_ARGS__)}
^
dschwoerer
previously approved these changes
Jul 1, 2026
dschwoerer
left a comment
dschwoerer
left a comment
Contributor
There was a problem hiding this comment.
Thanks for the cleanup!
…ix-docs-warnings
dschwoerer
previously approved these changes
Jul 8, 2026
dschwoerer
reviewed
Jul 8, 2026
dschwoerer
approved these changes
Jul 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is a bid to try and get the number of Sphinx warnings down, to ideally start using error on warnings.
The major issue now is things like:
which I think is complaining about overriding the pure virtual function. I don't know whether this is an issue with breathe or doxygen. Breathe is not super well maintained currently, so I might investigate other options.
I've fixed a massive chunk of these warnings by just not processing the
.cxxfiles. I think this is probably reasonable, but it might involve going through and moving docstrings to the headers. That will take a little bit of time to do.Making a draft now in case anyone has feedback or ideas on these changes.