Restructure Documentation #1679
Conversation
ginkgo-bot
added
reg:build
|
Link to the documentation at RTD: https://ginkgo-test.readthedocs.io/doxysphinx/index.html |
MarcelKoch
force-pushed
the
read-the-docs
branch
5 times, most recently
from
251d914 to
02a4a81
Compare
This does the following things: - add sphinx to create non-reference/api documentation - move doxygen stuff into a subdirectory of the sphinx configuration - enable read-the-docs to host documentation
The linop group is often added with other groups. These other groups are mostly subgroups of linop, so there is no need to specify it twice.
MarcelKoch
force-pushed
the
read-the-docs
branch
from
02a4a81 to
b54adfb
Compare
|
Sorry, clicked the close PR button by mistake. |
This link results in a 404 error. Could you regenerate it or update the link? |
|
This should work: https://ginkgo-test.readthedocs.io/doxysphinx/index.html |
|
Thanks, that link works! |
There was a problem hiding this comment.
I like the changes, and the documentation looks excellent!
However, when trying out the new documentation, I encountered an issue: It seems to be possible to access the old doxygen documentation, which leads to all links on the page becoming broken.
The easiest way to go to the old page is by clicking one of the links on the doxysphinx tab (not sure if that is the right expression) on the bottom right:
After clicking any of the links in there, I assume the old style is used, and all of the links on the Doxygen page don't work anymore.
Here is the Doxysphinx page (that you shared): https://ginkgo-test.readthedocs.io/doxysphinx/index.html
And here is the page with the broken links I got when clicking a link on the tab bottom right: https://ginkgo-test.readthedocs.io/user-guide/
Unfortunately, I don't know how to fix it (I don't know where this tab is coming from), but it must be addressed to improve the user experience (maybe by simply removing this tab altogether).
| - | | ||
| cmake -S . -B build \ | ||
| -DGINKGO_BUILD_DOC=ON \ | ||
| -DGINKGO_DOC_GENERATE_PDF=OFF \ | ||
| -DGINKGO_BUILD_EXAMPLES=ON \ | ||
| -DGINKGO_BUILD_TESTS=OFF \ | ||
| -DGINKGO_BUILD_BENCHMARKS=OFF \ | ||
| -DGINKGO_BUILD_REFERENCE=ON \ | ||
| -DGINKGO_BUILD_OMP=OFF \ | ||
| -DGINKGO_BUILD_CUDA=OFF \ | ||
| -DGINKGO_BUILD_HIP=OFF \ | ||
| -DGINKGO_BUILD_SYCL=OFF \ | ||
| -DGINKGO_BUILD_MPI=OFF | ||
| cmake --build build -t doxygen -- -j | ||
| mkdir -p $READTHEDOCS_OUTPUT/html/ | ||
| mv build/doc/html/_doxygen $READTHEDOCS_OUTPUT/html/_doxygen |
There was a problem hiding this comment.
nit: This is different from our normal YAML style. I would prefer not to use the literal style (the |) of YAML and instead make the purpose clear through indentation:
| - | | |
| cmake -S . -B build \ | |
| -DGINKGO_BUILD_DOC=ON \ | |
| -DGINKGO_DOC_GENERATE_PDF=OFF \ | |
| -DGINKGO_BUILD_EXAMPLES=ON \ | |
| -DGINKGO_BUILD_TESTS=OFF \ | |
| -DGINKGO_BUILD_BENCHMARKS=OFF \ | |
| -DGINKGO_BUILD_REFERENCE=ON \ | |
| -DGINKGO_BUILD_OMP=OFF \ | |
| -DGINKGO_BUILD_CUDA=OFF \ | |
| -DGINKGO_BUILD_HIP=OFF \ | |
| -DGINKGO_BUILD_SYCL=OFF \ | |
| -DGINKGO_BUILD_MPI=OFF | |
| cmake --build build -t doxygen -- -j | |
| mkdir -p $READTHEDOCS_OUTPUT/html/ | |
| mv build/doc/html/_doxygen $READTHEDOCS_OUTPUT/html/_doxygen | |
| - cmake -S . -B build | |
| -DGINKGO_BUILD_DOC=ON | |
| -DGINKGO_DOC_GENERATE_PDF=OFF | |
| -DGINKGO_BUILD_EXAMPLES=ON | |
| -DGINKGO_BUILD_TESTS=OFF | |
| -DGINKGO_BUILD_BENCHMARKS=OFF | |
| -DGINKGO_BUILD_REFERENCE=ON | |
| -DGINKGO_BUILD_OMP=OFF | |
| -DGINKGO_BUILD_CUDA=OFF | |
| -DGINKGO_BUILD_HIP=OFF | |
| -DGINKGO_BUILD_SYCL=OFF | |
| -DGINKGO_BUILD_MPI=OFF | |
| - cmake --build build -t doxygen -- -j | |
| - mkdir -p $READTHEDOCS_OUTPUT/html/ | |
| - mv build/doc/html/_doxygen $READTHEDOCS_OUTPUT/html/_doxygen |
| * | ||
| * <tr valign="top"> | ||
| * <td>@subpage kokkos_assembly</td> | ||
| * <td> Use Kokkos to assemble as simple linear system. |
There was a problem hiding this comment.
nit: typo
| * <td> Use Kokkos to assemble as simple linear system. | |
| * <td> Use Kokkos to assemble a simple linear system. |
| Tutorial <https://github.com/ginkgo-project/ginkgo/wiki/Tutorial:-Building-a-Poisson-Solver> | ||
| Examples <_doxygen/html/Examples.html#https://> | ||
| Publications <publications> | ||
| contributing | ||
| Using Ginkgo <using-ginkgo> | ||
| API <_doxygen/html/index.html#https://> | ||
| ::: No newline at end of file |
There was a problem hiding this comment.
Is this the list of items on the left of the page you linked (https://ginkgo-test.readthedocs.io/doxysphinx/index.html) ? If so, there is an additional About Licensing between Using Ginkgo and the API that I can't explain.
|
closed in favor of #1813 |
3 participants
This PR splits the documentation into a part that is generated by sphinx and one that is generated by doxygen.
The doxygen part will cover only the reference API documentation, and anything else will be left to sphinx. The full separation is not done in this PR.
Changes:
usrdoc is available, thedevdoc is removed. IMO there is no need for adevdoc, since we can expect developers to look into the Ginkgo source code and discover the documentation there.TODO: