Fix various documentation issues #2844
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!
|
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:
|
manual/sphinx/conf.py
Outdated
| sys.path.append("../../tools/pylib/boutpp") | ||
| sys.path.append("../../tools/pylib/boutconfig") |
There was a problem hiding this comment.
Why did you do this?
That breaks the RTD build:
https://bout-dev--2844.org.readthedocs.build/en/2844/_apidoc/boutpp.html#boutpp-api
https://bout-dev.readthedocs.io/en/latest/_apidoc/boutpp.html#boutpp-api
The tools are directly in boutpp and boutconfig ...
There was a problem hiding this comment.
This was to stop generating the docs for the other directories under pylib, and to be explicit about what's built here. It looks like it built the docs for everything except these two, which is very odd. Not sure what's going on!
There was a problem hiding this comment.
I think the other ones get pip installed?
I haven't checked though!
Anyway, for zoidberg we currently don't build the docs but reference the bout++ docs, so if you want to drop zoidberg here, we should add zoidberg independently.
Also, it would be better to remove the sections, rather then to have them being empty because python cannot find the modules.
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"
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.