Merge pull request #10 from emdgroup/docs/furo_theme

Use furo theme for docs

CHANGELOG.md

@@ -14,9 +14,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Reworked README for GitHub landing page
-
-### Changed
 - Now has concise contribution guidelines
+- Use Furo theme for documentation
+
 
 ### Removed
 - `--debug` flag for documentation building

docs/_static/custom.css

@@ -0,0 +1,29 @@
+/*This file contains the options for changing the generated HTML Output*/
+
+/*Remove border around logo*/
+.sidebar-logo-container {
+    margin: 0;
+}
+
+.sidebar-search-container {
+    margin-top: 0;
+}
+
+a.sidebar-brand {
+    padding: 0;
+}
+
+/*Reduce left and right margins*/
+
+.sidebar-drawer {
+    width: calc(40% - 26em);
+}
+
+.content {
+    width: calc(100% - 10em);
+}
+
+/*The color of the "Search" placeholder in the sidebar*/
+.sidebar-search::placeholder {
+    color: #ffdcb9;
+}

docs/conf.py

@@ -24,7 +24,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "BayBE"
-copyright = "2022-2023, Merck KGaA"
+copyright = "2022-2023 Merck KGaA, Darmstadt, Germany and/or its affiliates. All rights reserved."  # noqa
 author = "Martin Fitzner, Adrian Šošić, Alexander Hopp, Alex Lee"
 
 
@@ -122,9 +122,95 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 # We use the read-the-docs theme
-html_theme = "sphinx_rtd_theme"
+html_theme = "furo"
 # We want to have links to the source
 html_show_sourcelink = True
+# Use the provided html theme
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+# Change the colors. The following colors are used:
+BROWN = "#ffdcb9"
+DARK_BLUE = "#0f69af"
+LIGHT_BLUE = "#65bbca"
+DARK_GRAY = "#212723"  # The dark gray of Githubs Dimmed Theme
+LIGHT_GRAY = "#2c333b"  # The dark gray of Githubs Dimmed Theme
+html_theme_options = {
+    # We do not want the name of the package shown separately in the left sidebar
+    "sidebar_hide_name": True,
+    # Colors for light mode. For details on the keys, see colors for dark mode.
+    "light_css_variables": {
+        "color-background-secondary": DARK_BLUE,
+        "color-background-border": "transparent",
+        # Colors of headings in left sidebar
+        # "color-foreground-primary": "white",
+        "color-brand-primary": BROWN,
+        "color-brand-secondary": BROWN,
+        # "Muted" text
+        "color-foreground-muted": "white",
+        "color-highlight-on-target": BROWN,
+        "color-api-background": BROWN,
+        "color-api-pre-name": LIGHT_BLUE,
+        "color-api-name": DARK_BLUE,
+        "color-toc-item-text": "black",
+        "color-inline-code-background": "#efeff4",  # Very lightlight gray
+        # Color of search bar when clicking search
+        "color-sidebar-search-background--focus": DARK_BLUE,
+        "color-link": DARK_BLUE,
+        # Color when hovering over the item expander in the left sidebar.
+        "color-sidebar-item-expander-background--hover": LIGHT_BLUE,
+        # Color when hovering over an item in the left sidebar
+        "color-sidebar-item-background--hover": LIGHT_BLUE,
+        # Color of the links in the left side bar
+        "color-sidebar-link-text": "white",
+        # Color of text in the right navigation side bar when chosen
+        "color-toc-item-text--active": DARK_BLUE,
+        # The color around the search bar
+        "color-sidebar-search-border": BROWN,
+        # Color of the search text and icon
+        "color-sidebar-search-text": "white",
+        "color-sidebar-search-icon": BROWN,
+    },
+    # Colors for dark mode.
+    "dark_css_variables": {
+        # Background of content
+        "color-background-primary": LIGHT_GRAY,
+        "color-background-secondary": DARK_BLUE,
+        # Colors of texts and other "foreground" elements
+        "color-foreground-primary": "white",
+        "color-foreground-secondary": "white",
+        # General borders
+        "color-background-border": "transparent",
+        # Two general colors for several aspects of the color cheme
+        "color-brand-primary": BROWN,
+        "color-brand-secondary": "black",
+        # "Muted" text
+        "color-foreground-muted": "white",
+        # Background of the current target (e.g. after clicking on an internal link)
+        "color-highlight-on-target": DARK_BLUE,
+        # General backgrounds of headers and similar in the API
+        "color-api-background": DARK_BLUE,
+        # Names in the API
+        "color-api-name": BROWN,
+        # Prefix in API names (e.g. baybe.campaign)
+        "color-api-pre-name": "white",
+        # Background formlinks
+        "color-inline-code-background": "transparent",
+        # The color of links
+        "color-link": BROWN,
+        # Color of text in the right navigation side bar
+        "color-toc-item-text": LIGHT_BLUE,
+        # Color of search bar when clicking search
+        "color-sidebar-search-background--focus": DARK_BLUE,
+    },
+    # Logos. Location is relative to _static folder.
+    "light_logo": "logo1.svg",  # Logo for light mode
+    "dark_logo": "logo1.svg",  # Logo for dark mode
+}
+
+# Ignored links for linkcheck
+if "BAYBE_DOCS_LINKCHECK_IGNORE" in os.environ:
+    linkcheck_ignore = ["https://emdgroup.github.io/baybe/"]
+
 
 # Everything in the module has the prefix baybe
 modindex_common_prefix = ["baybe."]

docs/index.md

@@ -2,13 +2,16 @@
 :maxdepth: 2
 :titlesonly:
 :caption: General
+:hidden:
 
-
-Overview <self>
 Readme <misc/readme_link>
 User Guide <userguide/userguide>
 Examples <examples/examples>
-How To Contribute <misc/contributing_link>
+Contribute <misc/contributing_link>
+```
+
+```{include} ../README.md
+:relative-docs: docs/
 ```
 
 # Package documentation
@@ -17,7 +20,7 @@ How To Contribute <misc/contributing_link>
    :toctree: _autosummary
    :template: custom-module-template.rst
    :recursive:
-   :caption: Package documentation
+   :caption: Package
 
    baybe
 ```
@@ -26,6 +29,7 @@ How To Contribute <misc/contributing_link>
     :maxdepth: 2
     :titlesonly:
     :caption: Misc
+    :hidden:
 
     Known Issues <known_issues>
     FAQ <faq>

docs/scripts/convert_code_to_documentation.py

@@ -4,7 +4,7 @@
 import os
 import pathlib
 import shutil
-from subprocess import DEVNULL, STDOUT, CalledProcessError, check_call, run
+from subprocess import DEVNULL, STDOUT, check_call, run
 
 from tqdm import tqdm
 
@@ -74,8 +74,6 @@ def create_example_documentation(example_dest_dir: str):
 
     Args:
         example_dest_dir: The destination directory.
-        debug: Flag indicating whether conversion should be run in debug mode with
-            more information.
     """
     # Folder where the .md files created are stored
     examples_directory = pathlib.Path(example_dest_dir)
@@ -95,7 +93,7 @@ def create_example_documentation(example_dest_dir: str):
     # examples
     ex_file = "# Examples\n\nThese examples show how to use BayBE.\n\n```{toctree}\n"
 
-    # Iterate over the directories. Only print output in debug mode.
+    # Iterate over the directories.
     for sub_directory in (pbar := tqdm(ex_directories)):
         # Get the name of the current folder
         # Format it by replacing underscores and capitalizing the words
@@ -151,7 +149,6 @@ def create_example_documentation(example_dest_dir: str):
             ]
             to_markdown = ["jupyter", "nbconvert", "--to", "markdown", notebook_path]
 
-            # Check whether the debug flag is being used.
             check_call(convert_execute, stdout=DEVNULL, stderr=STDOUT)
             check_call(
                 to_markdown,
@@ -197,6 +194,37 @@ def create_example_documentation(example_dest_dir: str):
             subdirectory.rmdir()
 
 
+def adjust_banner(file_path: str, light_banner: str, dark_banner: str) -> None:
+    """Adjust the banner to have different versions for light and dark furo style.
+
+    Args:
+        file_path: The (relative) path to the file that needs to be adjusted. Typically
+            the index and README_link file.
+        light_banner: The name of the light mode banner.
+        dark_banner: The name of the dark mode banner.
+    """
+    with open(file_path, "r") as file:
+        lines = file.readlines()
+
+    line_index = None
+    for i, line in enumerate(lines):
+        if "banner" in line:
+            line_index = i
+            break
+
+    if line_index is not None:
+        line = lines[line_index]
+        light_line = line.replace("reference external", "reference external only-light")
+        lines[line_index] = light_line
+        # lines.insert(line_index + 1, light_line)
+        dark_line = light_line.replace("only-light", "only-dark")
+        dark_line = dark_line.replace(light_banner, dark_banner)
+        lines[line_index + 1] = dark_line
+
+        with open(file_path, "w") as file:
+            file.writelines(lines)
+
+
 # Collect all of the directories and delete them if they still exist.
 directories = [sdk_dir, autosummary_dir, build_dir, destination_dir]
 
@@ -232,19 +260,21 @@ def create_example_documentation(example_dest_dir: str):
     create_example_documentation(example_dest_dir="docs/examples")
 
 
-try:
+if FORCE:
+    print("Force-building the documentation, ignoring errors and warnings.")
+    # In force mode, we do not want to fail, even if an error code is returned.
+    # Hence, we use run instead of check_call
+    run(link_call, check=False)
+    run(building_call + ["--keep-going"], check=False)
+else:
     check_call(link_call)
     check_call(building_call)
-except CalledProcessError:
-    print(
-        """One process raised a critical error. Consider running with --force flag."""
-    )
-    if FORCE:
-        print("Force-building the documentation, ignoring errors and warnings.")
-        # We do not want to fail the next two calls, even if an error code is returned.
-        # Hence, we usw run instead of check_call
-        run(link_call, check=False)
-        run(building_call + ["--keep-going"], check=False)
+
+# Adjust the banner in the index and the README
+adjust_banner("docs/build/index.html", light_banner="banner2", dark_banner="banner1")
+adjust_banner(
+    "docs/build/misc/readme_link.html", light_banner="banner2", dark_banner="banner1"
+)
 
 # Clean the other files
 for directory in [sdk_dir, autosummary_dir]:

docs/userguide/campaigns.md

@@ -1,3 +1,4 @@
 # Campaigns
 
-This file contains information about campaigns.
+This page will soon contain information about campaigns.
+In the meantime, please see the [examples](../../examples/examples) instead.

docs/userguide/constraints.md

@@ -1,3 +1,4 @@
 # Constraints
 
-This file contains information about constraints.
+This page will soon contain information about constraints.
+In the meantime, please see the [examples](../../examples/examples) instead.

docs/userguide/parameters.md

@@ -1,3 +1,4 @@
 # Parameters
 
-This should contain information about parameters.
+This page will soon contain information about parameters.
+In the meantime, please see the [examples](../../examples/examples) instead.

docs/userguide/recommender.md

@@ -1,3 +1,4 @@
 # Recommenders
 
-This file contains information about recommenders.
+This page will soon contain information about recommenders.
+In the meantime, please see the [examples](../../examples/examples) instead.

docs/userguide/searchspace.md

@@ -1,3 +1,4 @@
 # Search spaces
 
-This file contains information about search spaces.
+This page will soon contain information about search spaces.
+In the meantime, please see the [examples](../../examples/examples) instead.

docs/userguide/simulation.md

@@ -1,3 +1,4 @@
 # Simulation
 
-This file contains information about simulations.
+This page will soon contain information about simulations.
+In the meantime, please see the [examples](../../examples/examples) instead.

docs/userguide/strategy.md

@@ -1,3 +1,4 @@
 # Strategies
 
-This file contains information about strategies.
+This page will soon contain information about strategies.
+In the meantime, please see the [examples](../../examples/examples) instead.

docs/userguide/surrogates.md

@@ -1,3 +1,4 @@
 # Surrogates
 
-This file contains information about surrogates.
+This page will soon contain information about surrogates.
+In the meantime, please see the [examples](../../examples/examples) instead.

docs/userguide/targets.md

@@ -1,3 +1,4 @@
-# The file on targets
+# Targets
 
-This file should contain information about targets
+This page will soon contain information about targets.
+In the meantime, please see the [examples](../../examples/examples) instead.

docs/userguide/userguide.md

@@ -1,6 +1,8 @@
 # User guide
 
-This file contains a general user guide for BayBE.
+Here, you will soon find user guides with instructions on how to use BayBE.
+These are currently being worked on.
+In the meantime, we refer to the [examples](../../examples/examples) instead.
 
 ```{toctree}
 Campaigns <campaigns>

pyproject.toml

@@ -63,12 +63,12 @@ dev = [
 
 docs = [
     "baybe[examples]",  # docs cannot be built without running examples
+    "furo>=2023.09.10", # Theme used for documentation
     "p2j>=1.3.2",
     "jupyter>=1.0.0",
     "myst-parser>=2.0.0",
     "sphinx>=7.1.1",
     "sphinx-autodoc-typehints>=1.24.0",
-    "sphinx-rtd-theme>=1.3.0",
 ]
 
 examples = [

tox.ini

@@ -46,7 +46,7 @@ commands =
     pip-audit {env:EXCLUDES:}
 
 [testenv:docs,docs-py{38,39,310,311}]
-description = Build documentation and verify, including examples. Results are stored in docs/build.
+description = Build documentation
 extras = docs
 commands = 
     python --version