Conversation
Codecov Report
@@ Coverage Diff @@
## master #446 +/- ##
==========================================
- Coverage 97.22% 96.57% -0.66%
==========================================
Files 218 222 +4
Lines 12546 13038 +492
==========================================
+ Hits 12198 12591 +393
- Misses 348 447 +99
Continue to review full report at Codecov.
|
|
@jedbrown I have integrated our doxygen code documentation with breathe. Unfortunately, the lowest-maintainability option that they provide with the directive |
|
Update: Since we have two pretty lengthy markdown files with API documentation and developer notes, namely, The only outstanding issue in this PR right now is the ability to parse previously existing doxygen markdown directives, for instance |
|
Further update: Files At this point, this is ready for review. Thanks. |
|
CodeCov is confused but CI passes. |
|
Do you get these? |
Unfortunately, I searched for the first warning message Have you built the xml files first by running I do get some warnings for duplicate labels, unfortunately I wasn't able to figure out how to remove them yet. |
|
Looks like the "function based directive" warning is a breathe issue: breathe-doc/breathe#467 There are some other warnings, some of which are related to redundant tags. Site is live here: https://libceed.readthedocs.io/en/latest/ |
|
This is looking great! One thought - is there a way to integrate the code of conduct and contributing info? It seems like those would be appropriate additions to the "Developer Notes" section. |
|
Am I correct that the plan is to remove the codedocs site and update the top level README with the new readthedocs site? |
|
@jeremylt I think yes, this should replace the codedocs website, though we may still want Doxygen code listings because it can hyperlink all functions -- we don't know how to do that in Sphinx. |
valeriabarra
force-pushed
the
user-manual
branch
from
2babc7e to
727a2ff
Compare
jedbrown
force-pushed
the
user-manual
branch
5 times, most recently
from
a5c0f2b to
65a6697
Compare
|
This will need the updates on master, but otherwise it looks like it might be ready? |
|
@jeremylt What is your opinion of this "mermaid" diagram? Keep or drop? https://libceed.readthedocs.io/en/latest/api/index.html The other issue that needs checking is the author list after upstream updates. I would prefer the examples.rst to be split into each directory -- it's already pretty long and will get longer if we do a legit explanation of the methodology in Navier-Stokes, for example. |
|
I think that the mermaid is a useful visualization to explain how we plug into user code. I like it. |
jedbrown
force-pushed
the
user-manual
branch
2 times, most recently
from
cb2763f to
d9898d4
Compare
|
@valeriabarra Thought we should make it nicer (using TikZ or an SVG editor). I lean toward the simplicity of being able to create them like this. My recent push fixes authorship maintenance. |
I'm a graphics fan but that's fine if it is the preferred way. Should we at least caption the image saying that it represents the schematic of the API classes or the role of libCEED? |
Thanks for the AUTHORS update. Will the AUTHORS file be automatically updated? |
|
|
|
I just like simple and maintainable. If you want to make a nicer figure, that'd be great, but I think there are probably more impactful ways to spend time. |
jedbrown
left a comment
jedbrown
left a comment
There was a problem hiding this comment.
I'm happy with merging. Once this and #463 are merged, we can split the examples.rst into separate files and make more complete documentation for the cubed sphere and Navier-Stokes cases. Let me know if you'd like help with Git logistics for squashing and merging coherently.
|
Yes please. I would be very thankful if you can make some git magic. |
The parser handles line comments fine. This also avoids malfunction in case // comments appear in ceed.h (the former rule excluded all lines containing '///' and ignored '//' lines, resulting in all subsequent lines being ignored).
…ions Helped-by: Valeria Barra <[email protected]> Squashed-by: Jed Brown <[email protected]>
Some technical notes about the expanded docs/process: * Doxygen is now restricted to API documentation. Sphinx docs are incomplete surrogates due to not hyperlinking code listings, though we hope the Doxygen site can be removed eventually. * PDF output uses XeTeX (unicode and OTF fonts) with TeX Gyre Pagella and DejaVu Sans Mono. You may need to install these fonts in order to build the PDF users manual. * Obtaining the author list from Git has not worked on ReadTheDocs (`git shortlog` is empty even though `git log` is not), so we automatically generate it on developer machines with `make doc`. If the author information is incorrect/mangled, edit .mailmap to fix the mapping. * Math semantics are based on the description here sphinx-doc/sphinx#3785 Sphinx chooses one of two setups for the maths. * If there is a single equation, then we wrap the maths in \begin{equation*} (or equation). * If there are multiple equations (as determined by the presence of an empty line), then we wrap the maths first in \begin{aligned} and then in \begin{align*} (or align). Co-authored-by: Jeremy L. Thompson <[email protected]> Co-authored-by: Jed Brown <[email protected]>
Breathe and/or Sphinx lacks support for restrict qualifiers, so use the workaround suggested here to hide the restrict qualifier from Breathe/Sphinx. breathe-doc/breathe#477 (comment) An alternative is to use the C domain for *.c and *.h files. This handles restrict, but reduces enum names to their numeric value. Once that Breathe/Sphinx bug is fixed, we could skip the restrict elision in favor of using the C domain.
3 participants
Our very first user manual!
It uses sphinx, which is able to read both Markdown (
although I still have to figure out some small thingssee below) and ReStructuredText files. Math formulas are rendered nicely in html directly from ReStructuredText files using the mathjax extension (a bit of reformatting using the proper directives is necessary if you want to convert a latex file straight to an rst file).TO DOs:
- [ ] Figure out how to properly parse and render existingthis seems to not be possible, but I have converted the\snippetfrom md files (see, e.g., libCEEDapi.md:238).mdfiles torstfiles and used different directives for code snippet inclusions.breathe.sphinxcontrib-bibtexor other available extensions.