diff --git a/CHANGELOG.md b/CHANGELOG.md index 4e389c055..e520803f8 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 000000000..b965bc8bc --- /dev/null +++ b/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; +} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 839328d44..43efc77ea 100644 --- a/docs/conf.py +++ b/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."] diff --git a/docs/index.md b/docs/index.md index 99591aac0..030896bfa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,13 +2,16 @@ :maxdepth: 2 :titlesonly: :caption: General +:hidden: - -Overview Readme User Guide Examples -How To Contribute +Contribute +``` + +```{include} ../README.md +:relative-docs: docs/ ``` # Package documentation @@ -17,7 +20,7 @@ How To Contribute :toctree: _autosummary :template: custom-module-template.rst :recursive: - :caption: Package documentation + :caption: Package baybe ``` @@ -26,6 +29,7 @@ How To Contribute :maxdepth: 2 :titlesonly: :caption: Misc + :hidden: Known Issues FAQ diff --git a/docs/scripts/convert_code_to_documentation.py b/docs/scripts/convert_code_to_documentation.py index 0da4d6ec2..9dbefaf5b 100644 --- a/docs/scripts/convert_code_to_documentation.py +++ b/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]: diff --git a/docs/userguide/campaigns.md b/docs/userguide/campaigns.md index b8114a9a2..39077b7b0 100644 --- a/docs/userguide/campaigns.md +++ b/docs/userguide/campaigns.md @@ -1,3 +1,4 @@ # Campaigns -This file contains information about campaigns. \ No newline at end of file +This page will soon contain information about campaigns. +In the meantime, please see the [examples](../../examples/examples) instead. \ No newline at end of file diff --git a/docs/userguide/constraints.md b/docs/userguide/constraints.md index 91fc1668b..42bc6db66 100644 --- a/docs/userguide/constraints.md +++ b/docs/userguide/constraints.md @@ -1,3 +1,4 @@ # Constraints -This file contains information about constraints. \ No newline at end of file +This page will soon contain information about constraints. +In the meantime, please see the [examples](../../examples/examples) instead. \ No newline at end of file diff --git a/docs/userguide/parameters.md b/docs/userguide/parameters.md index ff0ecb5fd..72896df0a 100644 --- a/docs/userguide/parameters.md +++ b/docs/userguide/parameters.md @@ -1,3 +1,4 @@ # Parameters -This should contain information about parameters. \ No newline at end of file +This page will soon contain information about parameters. +In the meantime, please see the [examples](../../examples/examples) instead. \ No newline at end of file diff --git a/docs/userguide/recommender.md b/docs/userguide/recommender.md index 52f293dbd..e48490596 100644 --- a/docs/userguide/recommender.md +++ b/docs/userguide/recommender.md @@ -1,3 +1,4 @@ # Recommenders -This file contains information about recommenders. \ No newline at end of file +This page will soon contain information about recommenders. +In the meantime, please see the [examples](../../examples/examples) instead. \ No newline at end of file diff --git a/docs/userguide/searchspace.md b/docs/userguide/searchspace.md index fce88bacd..95f8da2ab 100644 --- a/docs/userguide/searchspace.md +++ b/docs/userguide/searchspace.md @@ -1,3 +1,4 @@ # Search spaces -This file contains information about search spaces. \ No newline at end of file +This page will soon contain information about search spaces. +In the meantime, please see the [examples](../../examples/examples) instead. \ No newline at end of file diff --git a/docs/userguide/simulation.md b/docs/userguide/simulation.md index 5a9e0df1e..f603c7206 100644 --- a/docs/userguide/simulation.md +++ b/docs/userguide/simulation.md @@ -1,3 +1,4 @@ # Simulation -This file contains information about simulations. \ No newline at end of file +This page will soon contain information about simulations. +In the meantime, please see the [examples](../../examples/examples) instead. \ No newline at end of file diff --git a/docs/userguide/strategy.md b/docs/userguide/strategy.md index 31164536f..7c1bcc8a4 100644 --- a/docs/userguide/strategy.md +++ b/docs/userguide/strategy.md @@ -1,3 +1,4 @@ # Strategies -This file contains information about strategies. \ No newline at end of file +This page will soon contain information about strategies. +In the meantime, please see the [examples](../../examples/examples) instead. \ No newline at end of file diff --git a/docs/userguide/surrogates.md b/docs/userguide/surrogates.md index f2d32866d..7214c3ffd 100644 --- a/docs/userguide/surrogates.md +++ b/docs/userguide/surrogates.md @@ -1,3 +1,4 @@ # Surrogates -This file contains information about surrogates. \ No newline at end of file +This page will soon contain information about surrogates. +In the meantime, please see the [examples](../../examples/examples) instead. \ No newline at end of file diff --git a/docs/userguide/targets.md b/docs/userguide/targets.md index 3c4c3d0c4..f6adea1e4 100644 --- a/docs/userguide/targets.md +++ b/docs/userguide/targets.md @@ -1,3 +1,4 @@ -# The file on targets +# Targets -This file should contain information about targets \ No newline at end of file +This page will soon contain information about targets. +In the meantime, please see the [examples](../../examples/examples) instead. \ No newline at end of file diff --git a/docs/userguide/userguide.md b/docs/userguide/userguide.md index 42bf7b64f..38810a2a7 100644 --- a/docs/userguide/userguide.md +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index ae43ad243..ddb0f8320 100644 --- a/pyproject.toml +++ b/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 = [ diff --git a/tox.ini b/tox.ini index 0b057466e..6c93fc0bb 100644 --- a/tox.ini +++ b/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