Restructure Documentation #1813

MarcelKoch · 2025-03-20T16:45:51Z

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:

adds sphinx configuration
make doxygen available for sphinx
simplify doxygen setup
- only the usr doc is available, the dev doc is removed. IMO there is no need for a dev doc, since we can expect developers to look into the Ginkgo source code and discover the documentation there.
fix some existing documentation (grouping, markdown files)
use read-the-docs instead of GH pages to deploy documentation

This is a continuation from #1679. Compared to the previous PR, this has a cleaner integration of doxygen into the documentation build by sphinx.

Link to generated docs: https://ginkgo-test.readthedocs.io/doxysphinx/index.html

Todo:

move to proper RTD space

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. Signed-off-by: Marcel Koch <marcel.koch@kit.edu>

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 Signed-off-by: Marcel Koch <marcel.koch@kit.edu>

Signed-off-by: Marcel Koch <marcel.koch@kit.edu>

- spelling - fix yaml formatting Co-authored-by: Thomas Grützmacher <thomas.gruetzmacher@tum.de>

yhmtsai · 2025-03-24T09:41:35Z

Plain program under the example shows empty block.
https://ginkgo-test.readthedocs.io/doxysphinx/doxygen/html/simple_solver.html

yhmtsai

I do not review the major part yet

README.md

yhmtsai · 2025-03-24T09:43:58Z

doc/_templates/article-header-buttons.html

+
+{#
+Copied from: https://github.com/executablebooks/sphinx-book-theme/blob/master/src/sphinx_book_theme/theme/sphinx_book_theme/macros/buttons.html
+to remove the light/dark theme switcher button


why to remove light/data theme button?

because the doxygen API doesn't work with it. The doxygen thing will not change entirely, so there are always some blocks which are light colored.

I see. I am using dark theme. It hurts my eyes in some api pages like the following. I will not ask the changes about the style in this PR, but this will be definitely changed by setting background/font-color always or finding a color theme can fit dark/light theme well

This image is exactly the issue I mentioned. I have no idea how to fix those white blocks, so I would put this as an issue to fix later.

Maybe we can change the Sphinx theme ? I prefer ones where both dark and light themes work well. Some themes which seem to be quite nice:

https://sphinx-book-theme.readthedocs.io/en/stable/

https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html

In particular, the PyData seems nice, because it has support for Jupyter extensions, which could be useful for us.

The current theme is sphinx-book. Because of doxysphinx, we are limited to the sphinx themes supported by them: https://boschglobal.github.io/doxysphinx/#caveats.
The issue with the light/dark theme isn't due to the sphinx theme, it's due to doxygen. I'm sure it's possible to get it working, but I don't have it on my priority list.

Honestly, I am not sure how useful the detailed doxygen documentation is. It might be better to not have the complete class/namespace list, but only focus on specific user-facing API and integrate it in the Sphinx documentation through breathe: https://breathe.readthedocs.io/en/latest/

Breathe makes the doxygen API available as sphinx docs, which has the advantage of simpler integration, but the generated formatting of C++ API is just plain horrible. Since Sphinx is python focus it doesn't care about parameter types, so types aren't aligned for multi-line function signatures.

yhmtsai · 2025-03-24T09:48:22Z

doc/doxygen/headers/jacobi.hpp

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors


should jacobi.hpp be deleted in general?

I don't know, this just keeps all of the documentation as it currently is. This PR changes only how it's presented.

include/ginkgo/core/matrix/hybrid.hpp

.readthedocs.yaml

doc/conf.py.in

- deactivate unnecessary cmake options - typos - generate sphinx config info Co-authored-by: Yu-Hsiang M. Tsai <yhmtsai@gmail.com>

MarcelKoch · 2025-03-24T15:56:55Z

Plain program under the example shows empty block. https://ginkgo-test.readthedocs.io/doxysphinx/doxygen/html/simple_solver.html

Should be fixed now.

yhmtsai

need to remove something like GINKGO_DOC_GENERATE_DEV in install.md

doc/doxygen/Doxyfile.in

doc/doxygen/examples/examples.hpp.in

doc/doxygen/mainpage.md

yhmtsai · 2025-03-24T16:31:04Z

doc/_templates/article-header-buttons.html

+
+{#
+Copied from: https://github.com/executablebooks/sphinx-book-theme/blob/master/src/sphinx_book_theme/theme/sphinx_book_theme/macros/buttons.html
+to remove the light/dark theme switcher button


I see. I am using dark theme. It hurts my eyes in some api pages like the following. I will not ask the changes about the style in this PR, but this will be definitely changed by setting background/font-color always or finding a color theme can fit dark/light theme well

yhmtsai · 2025-03-24T16:37:51Z

doc/doxygen/helpers.cmake

+        add_custom_command(TARGET "doxygen" POST_BUILD
+            COMMAND make
+            COMMAND "${CMAKE_COMMAND}" -E copy refman.pdf
+            "${CMAKE_CURRENT_BINARY_DIR}/${name}.pdf"


name is undefined here

doc/CMakeLists.txt

yhmtsai · 2025-03-24T16:58:17Z

doc/CMakeLists.txt

+    CREATE_LINK ${Ginkgo_SOURCE_DIR}/LICENSE ${Ginkgo_BINARY_DIR}/LICENSE
+    SYMBOLIC
+)
+file(


do we use test_install somewhere in documentation?

Yes, in install.md, right at the bottom.

I have tested it, but it actually downloaded the file.
I think it should be a link to the github page on the code rather than download that file.

doc/CMakeLists.txt

- copy directories directly - add missing examples - remove doc of removed cmake option Co-authored-by: Yu-Hsiang M. Tsai <yhmtsai@gmail.com>

yhmtsai · 2025-03-25T09:40:57Z

.readthedocs.yaml

@@ -0,0 +1,38 @@
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details


after this pr, we need to have registered in readthedoc. They will constantly fetch the repo or get the notification by some API hook. We do not need to do anything on our CI, right?

Yes, it gets automatically picked up: MarcelKoch#20.
I think all of the configuration happens on the read-the-docs side.

I see. I have also seen https://docs.readthedocs.com/platform/stable/guides/automation-rules.html such that we can set up a rule to just make the release and latest version documentation not-hidden to user.
We can make the normal branch either in hidden state (still build) or deactivated (no build).

yhmtsai · 2025-03-25T12:41:14Z

for code ```c++ will give a ++ in the beginning on the section https://ginkgo-test.readthedocs.io/doxysphinx/doxygen/html/group__Executor.html

MarcelKoch · 2025-03-25T15:56:54Z

for code ```c++ will give a ++ in the beginning on the section

It's the same for our current documentation: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/group__Executor.html#gae20be793db14dfd6249a315281201550.
I want to keep changes to the actual text of the documentation out of this PR, so I would not fix this right now.

- use link to GH repo instead of relative file path Co-authored-by: Yu-Hsiang M. Tsai <yhmtsai@gmail.com>

ginkgo-bot · 2025-03-25T16:09:36Z

Error: The following files need to be formatted:

core/solver/ir.cpp
include/ginkgo/core/multigrid/pgm.hpp

You can find a formatting patch under Artifacts here or run format! if you have write access to Ginkgo

yhmtsai

Thanks for adding this documentation configuration.
You seems to still update something. I will review again when you finish.

yhmtsai · 2025-03-25T17:12:20Z

.readthedocs.yaml

@@ -0,0 +1,38 @@
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details


I see. I have also seen https://docs.readthedocs.com/platform/stable/guides/automation-rules.html such that we can set up a rule to just make the release and latest version documentation not-hidden to user.
We can make the normal branch either in hidden state (still build) or deactivated (no build).

yhmtsai · 2025-03-25T17:21:08Z

doc/conf.py.in

+project = 'Ginkgo'
+copyright = f'{datetime.date.today().year}, The Ginkgo Authors'
+author = 'The Ginkgo Authors'
+release = '@Ginkgo_VERSION@'


maybe need the version tag to distinguish develop/release?

MarcelKoch added reg:documentation This is related to documentation. 1:ST:ready-for-review This PR is ready for review labels Mar 20, 2025

MarcelKoch self-assigned this Mar 20, 2025

MarcelKoch mentioned this pull request Mar 20, 2025

Restructure Documentation #1679

Closed

1 task

MarcelKoch and others added 13 commits March 20, 2025 17:48

[doc] remove unnecessary linop group

8f37acc

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. Signed-off-by: Marcel Koch <marcel.koch@kit.edu>

[doc] restructure documentation

03e2e64

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 Signed-off-by: Marcel Koch <marcel.koch@kit.edu>

[doc] generate path to doxygen via cmake

9ab2cb4

Signed-off-by: Marcel Koch <marcel.koch@kit.edu>

[ci] remove deploying GH pages.

9061206

[doc] add documentation on the documentation setup

9a8fca5

[doc] move top-level markdown files into docs

6525376

Signed-off-by: Marcel Koch <marcel.koch@kit.edu>

[doc] use doxysphinx to integrate API docs into sphinx

3c4601b

Signed-off-by: Marcel Koch <marcel.koch@kit.edu>

[doc] style the sphinx docs

aff66a6

[doc] require doxygen >= 1.9.0

97f8c12

[doc] move sphinx source to build dir

947a2d7

Signed-off-by: Marcel Koch <marcel.koch@kit.edu>

[doc] move doc/_doxygen to doc/doxygen

de469f4

Signed-off-by: Marcel Koch <marcel.koch@kit.edu>

[doc] pin python package versions

1d901fa

[doc] review updates:

353ea51

- spelling - fix yaml formatting Co-authored-by: Thomas Grützmacher <thomas.gruetzmacher@tum.de>

MarcelKoch force-pushed the doxysphinx branch from 9217908 to 353ea51 Compare March 20, 2025 16:53

yhmtsai reviewed Mar 24, 2025

View reviewed changes

MarcelKoch and others added 3 commits March 24, 2025 14:12

[doc] make plain program for examples available

7bd55b1

[doc] copy files instead of sym links

5d673b9

[doc] review updates:

1a32d51

- deactivate unnecessary cmake options - typos - generate sphinx config info Co-authored-by: Yu-Hsiang M. Tsai <yhmtsai@gmail.com>

yhmtsai requested changes Mar 24, 2025

View reviewed changes

[doc] review updates:

91e4866

- copy directories directly - add missing examples - remove doc of removed cmake option Co-authored-by: Yu-Hsiang M. Tsai <yhmtsai@gmail.com>

yhmtsai reviewed Mar 25, 2025

View reviewed changes

MarcelKoch added 6 commits March 25, 2025 11:48

WIP fix math

4d75f67

WIP fix math

9e75de0

WIP fix math

d3199ee

WIP fix math

4ccb263

WIP pdf

62855be

WIP pdf

1ed4e34

[doc] review updates:

f74430a

- use link to GH repo instead of relative file path Co-authored-by: Yu-Hsiang M. Tsai <yhmtsai@gmail.com>

yhmtsai reviewed Mar 25, 2025

View reviewed changes

yhmtsai mentioned this pull request Mar 28, 2025

Avoid CI run when only changes files in doc/ #1817

Merged

MarcelKoch marked this pull request as draft May 6, 2025 07:40

		@@ -1,4 +1,4 @@
		// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
		// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors

		@@ -0,0 +1,38 @@
		# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

Restructure Documentation #1813

Are you sure you want to change the base?

Restructure Documentation #1813

Uh oh!

Conversation

MarcelKoch commented Mar 20, 2025

Uh oh!

yhmtsai commented Mar 24, 2025

Uh oh!

yhmtsai left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pratikvn Mar 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MarcelKoch commented Mar 24, 2025

Uh oh!

yhmtsai left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

yhmtsai Mar 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yhmtsai commented Mar 25, 2025

Uh oh!

MarcelKoch commented Mar 25, 2025

Uh oh!

ginkgo-bot commented Mar 25, 2025

Uh oh!

yhmtsai left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

pratikvn Mar 31, 2025 •

edited

Loading

yhmtsai Mar 25, 2025 •

edited

Loading