Restructure Documentation #1813
There are no files selected for viewing
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details | ||
|
|
||
| # Required | ||
| version: 2 | ||
|
|
||
| # Set the OS, Python version and other tools you might need | ||
| build: | ||
| os: ubuntu-24.04 | ||
| apt_packages: | ||
| - doxygen | ||
| - cmake | ||
| - graphviz | ||
| tools: | ||
| python: "3.12" | ||
| jobs: | ||
| pre_build: | ||
| - cmake -S . -B build | ||
| -DGINKGO_BUILD_DOC=ON | ||
| -DGINKGO_DOC_GENERATE_PDF=OFF | ||
| -DGINKGO_BUILD_EXAMPLES=OFF | ||
| -DGINKGO_BUILD_TESTS=OFF | ||
| -DGINKGO_BUILD_BENCHMARKS=OFF | ||
| -DGINKGO_BUILD_REFERENCE=OFF | ||
| -DGINKGO_BUILD_OMP=OFF | ||
| -DGINKGO_BUILD_CUDA=OFF | ||
| -DGINKGO_BUILD_HIP=OFF | ||
| -DGINKGO_BUILD_SYCL=OFF | ||
| -DGINKGO_BUILD_MPI=OFF | ||
| - cmake --build build -t doxysphinx -- -j | ||
|
|
||
| # Build documentation in the "docs/" directory with Sphinx | ||
| sphinx: | ||
| configuration: build/doc/conf.py | ||
|
|
||
| # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html | ||
| python: | ||
| install: | ||
| - requirements: doc/requirements.txt | ||
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,24 +1,84 @@ | ||
| add_subdirectory(doxygen) | ||
|
|
||
| find_program(sphinx-build NAMES sphinx-build REQUIRED) | ||
| find_program(doxysphinx NAMES doxysphinx REQUIRED) | ||
|
|
||
| configure_file( | ||
| ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in | ||
| ${CMAKE_CURRENT_BINARY_DIR}/conf.py | ||
| @ONLY | ||
| ) | ||
|
|
||
| # Copy to the sphinx sources in the build directory | ||
| # These have to be actual copies, since sphinx (or myst) can't | ||
| # resolve (symbolic) links to files outside the sphinx source | ||
| # directory | ||
| set(files_to_copy ${CMAKE_CURRENT_SOURCE_DIR}/index.md) | ||
| set(dirs_to_copy) | ||
| set(dirs _static _templates developer-guide user-guide) | ||
| foreach(dir IN LISTS dirs) | ||
MarcelKoch marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| file(GLOB_RECURSE globs LIST_DIRECTORIES true CONFIGURE_DEPENDS ${dir}/*) | ||
| list(APPEND files_to_copy ${globs}) | ||
|
|
||
| cmake_path(ABSOLUTE_PATH dir OUTPUT_VARIABLE absolute_dir) | ||
| list(APPEND dirs_to_copy ${absolute_dir}) | ||
| endforeach() | ||
|
|
||
| foreach(in_source_file IN LISTS dirs_to_copy files_to_copy) | ||
| string( | ||
| REGEX REPLACE | ||
| "${CMAKE_CURRENT_SOURCE_DIR}" | ||
| "${CMAKE_CURRENT_BINARY_DIR}" | ||
| in_binary_file | ||
| ${in_source_file} | ||
| ) | ||
| if(IS_DIRECTORY ${in_source_file}) | ||
| file(MAKE_DIRECTORY ${in_binary_file}) | ||
| else() | ||
| file(COPY_FILE ${in_source_file} ${in_binary_file}) | ||
| endif() | ||
| endforeach() | ||
|
|
||
| # Create symlinks for top-level files referenced by documentation | ||
| # Here links are fine, since those files are not part of the documentation, | ||
| # they are just referenced | ||
| file(MAKE_DIRECTORY ${Ginkgo_BINARY_DIR}/test/test_install/) | ||
| file( | ||
| CREATE_LINK ${Ginkgo_SOURCE_DIR}/LICENSE ${Ginkgo_BINARY_DIR}/LICENSE | ||
| SYMBOLIC | ||
| ) | ||
| file( | ||
|
||
| CREATE_LINK | ||
| ${Ginkgo_SOURCE_DIR}/test/test_install/CMakeLists.txt | ||
| ${Ginkgo_BINARY_DIR}/test/test_install/CMakeLists.txt | ||
| SYMBOLIC | ||
| ) | ||
|
|
||
| if(DEFINED ENV{READTHEDOCS_OUTPUT}) | ||
| set(GINKGO_SPHINX_BUILD_DIR $ENV{READTHEDOCS_OUTPUT}/html) | ||
| else() | ||
| set(GINKGO_SPHINX_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/_build) | ||
MarcelKoch marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| endif() | ||
|
|
||
| add_custom_target( | ||
| doxysphinx | ||
| ALL | ||
| COMMAND | ||
| "${doxysphinx}" build --doxygen_cwd ${CMAKE_CURRENT_BINARY_DIR}/doxygen/ | ||
| ${CMAKE_CURRENT_BINARY_DIR} ${GINKGO_SPHINX_BUILD_DIR} | ||
| ${CMAKE_CURRENT_BINARY_DIR}/doxygen/Doxyfile | ||
| DEPENDS doxygen | ||
| COMMENT "Generating .rst files from doxygen documentation" | ||
| VERBATIM | ||
| ) | ||
|
|
||
| add_custom_target( | ||
| sphinx-doc | ||
| ALL | ||
| COMMAND | ||
| "${sphinx-build}" -j auto -b html --quiet ${CMAKE_CURRENT_BINARY_DIR} | ||
| ${GINKGO_SPHINX_BUILD_DIR} | ||
| DEPENDS doxysphinx | ||
| COMMENT "Generating sphinx documentation" | ||
| VERBATIM | ||
| ) | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| html{ | ||
| --pst-font-size-base: 17px; | ||
| } | ||
| html[data-theme="light"] { | ||
| --pst-color-primary: #F7A71E; | ||
| } | ||
| .bd-page-width { | ||
| max-width: 100rem; /* default is 88rem */ | ||
| } |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| {# | ||
| SPDX-FileCopyrightText: 2020 Chris Holdgraf | ||
|
|
||
| SPDX-License-Identifier: BSD-3-Clause | ||
| #} | ||
|
|
||
| {# | ||
| 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 | ||
|
There was a problem hiding this comment. why to remove light/data theme button? There was a problem hiding this comment. 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. There was a problem hiding this comment. 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 There was a problem hiding this comment. 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. There was a problem hiding this comment. 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:
In particular, the PyData seems nice, because it has support for Jupyter extensions, which could be useful for us. There was a problem hiding this comment. The current theme is There was a problem hiding this comment. 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/ There was a problem hiding this comment. 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. |
||
| #} | ||
|
|
||
| {% from "sphinx_book_theme/macros/buttons.html" import render_funcs with context %} | ||
|
|
||
| <div class="article-header-buttons"> | ||
| {%- for button in header_buttons -%} | ||
| {% set btype = button.get("type") %} | ||
| {% set bopts = button.copy() %} | ||
| {% set _ = bopts.pop("type") %} | ||
| {{ render_funcs[btype](**bopts) }} | ||
| {%- endfor -%} | ||
|
|
||
| {#- Extra theme buttons #} | ||
| {% include "search-button.html" %} | ||
| {% include "toggle-secondary-sidebar.html" %} | ||
| </div> | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| # Configuration file for the Sphinx documentation builder. | ||
| # | ||
| # For the full list of built-in configuration values, see the documentation: | ||
| # https://www.sphinx-doc.org/en/master/usage/configuration.html | ||
| import os | ||
| import datetime | ||
|
|
||
| # -- Project information ----------------------------------------------------- | ||
| # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information | ||
|
|
||
| project = 'Ginkgo' | ||
| copyright = f'{datetime.date.today().year}, The Ginkgo Authors' | ||
| author = 'The Ginkgo Authors' | ||
| release = '@Ginkgo_VERSION@' | ||
|
There was a problem hiding this comment. maybe need the version tag to distinguish develop/release? |
||
|
|
||
| # -- General configuration --------------------------------------------------- | ||
| # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration | ||
|
|
||
| extensions = [ | ||
| 'myst_parser', | ||
| 'sphinx.ext.autodoc', | ||
| 'sphinx.ext.intersphinx', | ||
| 'sphinx.ext.autosectionlabel', | ||
| 'sphinx.ext.todo', | ||
| 'sphinx.ext.coverage', | ||
| 'sphinx.ext.mathjax', | ||
| 'sphinx.ext.ifconfig', | ||
| 'sphinx.ext.viewcode', | ||
| 'sphinx_sitemap', | ||
| 'sphinx.ext.inheritance_diagram', | ||
| 'sphinxcontrib.doxylink', | ||
| ] | ||
|
|
||
| templates_path = ['_templates'] | ||
| exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] | ||
|
|
||
| highlight_language = 'c++' | ||
|
|
||
| # -- Options for HTML output ------------------------------------------------- | ||
| # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output | ||
|
|
||
| html_static_path = ['_static'] | ||
| html_css_files = ['css/custom.css'] | ||
| html_theme = 'sphinx_book_theme' | ||
| html_theme_options = { | ||
| 'repository_url': 'https://github.com/ginkgo-project/ginkgo/', | ||
| 'use_repository_button': True, | ||
| 'use_fullscreen_button': True, | ||
| 'use_download_button': False, | ||
| # remove the light/dark mode switcher as it doesn't work properly on doxygen pages | ||
| "article_header_end": ["article-header-buttons"] | ||
| } | ||
| html_logo = '@Ginkgo_SOURCE_DIR@/assets/logo.png' | ||
| html_favicon = '@Ginkgo_SOURCE_DIR@/assets/favicon.ico' | ||
| html_title = f'{project} v{release}' | ||
|
|
||
| # Define the canonical URL if you are using a custom domain on Read the Docs | ||
| html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "") | ||
|
|
||
| read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True' | ||
|
|
||
| # Tell Jinja2 templates the build is running on Read the Docs | ||
| if read_the_docs_build: | ||
| if "html_context" not in globals(): | ||
| html_context = {} | ||
| html_context["READTHEDOCS"] = True | ||
|
|
||
|
|
||
| # -- MyST configuration ------------------------------------------------------- | ||
| # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html | ||
|
|
||
| myst_enable_extensions = [ | ||
| "amsmath", | ||
| "colon_fence", | ||
| "deflist", | ||
| "dollarmath", | ||
| "linkify", | ||
| "replacements", | ||
| "smartquotes" | ||
| ] | ||
| myst_heading_anchors = 3 | ||
|
|
||
| # -- doxylink configuration ------------------------------------------------- | ||
| # https://sphinxcontrib-doxylink.readthedocs.io/en/stable/# | ||
|
|
||
| doxylink = { | ||
| 'doxy': ('@Ginkgo_BINARY_DIR@/doc/doxygen/html/tagfile.xml', 'doxygen/html') | ||
| } | ||
Oops, something went wrong.
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, it gets automatically picked up: MarcelKoch#20.
I think all of the configuration happens on the read-the-docs side.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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).