Merge pull request #1311 from msimberg/sphinx-immaterial

Update documentation to use sphinx-immaterial theme

docs/_static/pika.css

@@ -4,13 +4,11 @@
 /* file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) */
 
 .md-typeset h1 {
-    color: black;
     font-weight: 700;
     margin: 1em 0 0 0;
 }
 
 .md-typeset h2 {
-    color: black;
     font-weight: 500;
     margin: 1em 0 0 0;
 }
@@ -22,19 +20,3 @@
 .md-typeset ul li p {
     margin: 0 0;
 }
-
-.pre {
-    font-family: monospace;
-}
-
-.md-header-nav__topic {
-    font-weight: bold;
-}
-
-.md-typeset .headerlink {
-    opacity: 1;
-}
-
-.sig {
-    font-weight: bold;
-}

docs/api.rst

@@ -64,6 +64,8 @@ The ``pika/init.hpp`` header provides functionality to manage the pika runtime.
 .. doxygenfunction:: pika::suspend()
 .. doxygenfunction:: pika::is_runtime_initialized()
 
+.. versionadded:: 0.22.0
+
 .. doxygenstruct:: pika::init_params
    :members:
 
@@ -89,30 +91,40 @@ All sender adaptors are `customization point objects (CPOs)
 
 .. doxygenvariable:: pika::execution::experimental::drop_value
 
+.. versionadded:: 0.6.0
+
 .. literalinclude:: ../examples/documentation/drop_value_documentation.cpp
    :language: c++
    :start-at: #include
 
 .. doxygenvariable:: pika::execution::experimental::drop_operation_state
 
+.. versionadded:: 0.19.0
+
 .. literalinclude:: ../examples/documentation/drop_operation_state_documentation.cpp
    :language: c++
    :start-at: #include
 
 .. doxygenvariable:: pika::execution::experimental::split_tuple
 
+.. versionadded:: 0.12.0
+
 .. literalinclude:: ../examples/documentation/split_tuple_documentation.cpp
    :language: c++
    :start-at: #include
 
 .. doxygenvariable:: pika::execution::experimental::unpack
 
+.. versionadded:: 0.17.0
+
 .. literalinclude:: ../examples/documentation/unpack_documentation.cpp
    :language: c++
    :start-at: #include
 
 .. doxygenvariable:: pika::execution::experimental::when_all_vector
 
+.. versionadded:: 0.2.0
+
 .. literalinclude:: ../examples/documentation/when_all_vector_documentation.cpp
    :language: c++
    :start-at: #include

docs/conf.py

@@ -15,12 +15,13 @@
 release = version
 
 # General sphinx settings
-extensions = ["breathe", "recommonmark"]
+extensions = ["breathe", "sphinx_immaterial", "recommonmark"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 source_suffix = [".rst"]
 language = "English"
 primary_domain = "cpp"
 highlight_language = "cpp"
+language = "en"
 
 breathe_projects = {"pika": os.getenv("PIKA_DOCS_DOXYGEN_OUTPUT_DIRECTORY") + "/xml"}
 breathe_default_project = "pika"
@@ -33,43 +34,51 @@
 breathe_show_include = False
 
 show_warning_types = True
-# https://github.com/sphinx-doc/sphinx/issues/12300
-suppress_warnings = ["config.cache"]
 
 # HTML settings
 html_title = "pika"
-html_theme = "sphinx_material"
+html_theme = "sphinx_immaterial"
 html_static_path = ["_static"]
 html_css_files = ["pika.css"]
 html_show_sourcelink = False
-html_sidebars = {
-    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
-}
 html_theme_options = {
-    "nav_title": "pika",
-    "color_primary": "blue-grey",
-    "color_accent": "orange",
-    "base_url": "https://pikacpp.org",
+    "site_url": "https://pikacpp.org",
     "repo_url": "https://github.com/pika-org/pika",
-    "repo_name": "pika",
-    "html_minify": False,
-    # Disabled because of https://github.com/bashtage/sphinx-material/issues/123
-    "html_prettify": False,
-    "logo_icon": "",
-    "css_minify": True,
-    "repo_type": "github",
-    "globaltoc_depth": 2,
-    "master_doc": False,
-    "nav_links": [
-        {"href": "index", "internal": True, "title": "Overview"},
-        {"href": "usage", "internal": True, "title": "Usage"},
-        {"href": "api", "internal": True, "title": "API reference"},
-        {"href": "changelog", "internal": True, "title": "Changelog"},
-        {"href": "developer", "internal": True, "title": "Developer documentation"},
+    "features": [
+        "header.autohide",
+        "navigation.instant",
+        "navigation.tracking",
+        "search.highlight",
+        "search.share",
+    ],
+    "font": False,
+    "palette": [
+        {
+            "media": "(prefers-color-scheme)",
+            "toggle": {
+                "icon": "material/brightness-auto",
+                "name": "Switch to light mode",
+            },
+        },
+        {
+            "media": "(prefers-color-scheme: light)",
+            "scheme": "default",
+            "primary": "white",
+            "accent": "light-blue",
+            "toggle": {
+                "icon": "material/lightbulb-outline",
+                "name": "Switch to dark mode",
+            },
+        },
+        {
+            "media": "(prefers-color-scheme: dark)",
+            "scheme": "slate",
+            "primary": "black",
+            "accent": "light-blue",
+            "toggle": {
+                "icon": "material/lightbulb-outline",
+                "name": "Switch to system preference",
+            },
+        },
     ],
-    "heroes": {
-        "index": "pika is a C++ tasking library built on std::execution with fibers, CUDA, HIP, and MPI support",
-    },
-    "version_dropdown": False,
-    "table_classes": ["plain"],
 }

docs/index.rst

@@ -59,13 +59,13 @@ into HPX.
 
 The development of pika has been funded by:
 
-.. image:: _static/logo-cscs.jpg
+.. image:: _static/logo-cscs.png
    :width: 50%
    :align: center
    :alt: Swiss National Supercomputing Centre (CSCS)
    :target: https://www.cscs.ch
 
-.. image:: _static/logo-ethz.svg
+.. image:: _static/logo-ethz.png
    :width: 50%
    :align: center
    :alt: ETH Zurich

docs/requirements.txt

@@ -2,4 +2,5 @@
 sphinx
 breathe
 recommonmark
-sphinx_material
+# https://github.com/jbms/sphinx-immaterial/pull/338
+sphinx_immaterial@git+https://github.com/jbms/sphinx-immaterial.git@1f2a86a133dc07eabf932d77644d04feddac53d7

libs/pika/execution/include/pika/execution/algorithms/drop_operation_state.hpp

@@ -261,8 +261,6 @@ namespace pika::execution::experimental {
     /// than necessary which can prevent other algorithms from using those resources.
     /// \p drop_operation_state can be used to explicitly release the operation state, and thus
     /// associated resources, of previous senders.
-    ///
-    /// Added in 0.19.0.
     inline constexpr drop_operation_state_t drop_operation_state{};
 
 }    // namespace pika::execution::experimental

libs/pika/execution/include/pika/execution/algorithms/drop_value.hpp

@@ -144,7 +144,5 @@ namespace pika::execution::experimental {
     /// \brief Ignores all values sent by the predecessor sender, sending none itself.
     ///
     /// Sender adaptor that takes any sender and returns a new sender that sends no values.
-    ///
-    /// Added in 0.6.0.
     inline constexpr drop_value_t drop_value{};
 }    // namespace pika::execution::experimental

libs/pika/execution/include/pika/execution/algorithms/split_tuple.hpp

@@ -558,7 +558,5 @@ namespace pika::execution::experimental {
     /// each element in the input sender tuple. Each output sender signals completion whenever the
     /// input sender would have signalled completion. The predecessor sender must complete with
     /// exactly one tuple of at least one type.
-    ///
-    /// Added in 0.12.0.
     inline constexpr split_tuple_t split_tuple{};
 }    // namespace pika::execution::experimental

libs/pika/execution/include/pika/execution/algorithms/unpack.hpp

@@ -221,7 +221,5 @@ namespace pika::execution::experimental {
     /// any number of completion signatures for the value channel, each sending a single tuple-like.
     /// The adaptor does not unpack tuple-likes recursively. Any type that supports the tuple
     /// protocol can be used with the adaptor.
-    ///
-    /// Added in 0.17.0.
     inline constexpr unpack_t unpack{};
 }    // namespace pika::execution::experimental

libs/pika/execution/include/pika/execution/algorithms/when_all_vector.hpp

@@ -414,7 +414,5 @@ namespace pika::execution::experimental {
     /// An empty vector of senders completes immediately on start. When the input vector of senders
     /// contains senders that send no value the output sender sends no value instead of a vector.
     /// The senders in the input vector must send at most a single type.
-    ///
-    /// Added in 0.2.0.
     inline constexpr when_all_vector_t when_all_vector{};
 }    // namespace pika::execution::experimental

libs/pika/runtime/include/pika/runtime/runtime.hpp

@@ -441,8 +441,6 @@ namespace pika {
     ///
     /// Returns true between calls of \ref pika::start(int, char const* const*, init_params const&)
     /// and \ref pika::stop(), otherwise false.
-    ///
-    /// Added in 0.22.0.
     PIKA_EXPORT bool is_runtime_initialized() noexcept;
 }    // namespace pika