diff --git a/docs/_static/4insight-logo.svg b/docs/_static/4insight-logo.svg new file mode 100644 index 00000000..133c372e --- /dev/null +++ b/docs/_static/4insight-logo.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 00000000..b33b570d --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,270 @@ +@import "../basic.css"; + +:root { + /***************************************************************************** + * Theme config + **/ + --pst-header-height: 44px; + + /***************************************************************************** + * Font size + **/ + --pst-font-size-base: 18px; /* base font size - applied at body / html level */ + --pst-font-size-nav: 15px; /* navbar font size */ + --pst-font-size-breadcrumb: 16px; /* breadcrumb font size */ + --pst-font-size-logo: 16px; /* breadcrumb font size */ + + /***************************************************************************** + * Font family + **/ + /* These are adapted from https://systemfontstack.com/ */ + --pst-font-family-sansserif-system: "Trebuchet MS", -apple-system, + BlinkMacSystemFont, avenir next, avenir, "segoe ui", "helvetica neue", + helvetica, Ubuntu, roboto, noto, arial, sans-serif; + + --pst-font-family-serif-system: "Georgia", "Iowan Old Style", "Apple Garamond", + Baskerville, "Times New Roman", "Droid Serif", Times, "Source Serif Pro", + serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; + + --pst-font-family-monospace-system: SFMono-Regular, Menlo, Consolas, Monaco, + Liberation Mono, "Lucida Console", monospace; + + --pst-font-family-base: var(--pst-font-family-sansserif-system); + --pst-font-family-heading: var(--pst-font-family-sansserif-system); + --pst-font-family-monospace: var(--pst-font-family-monospace-system); + + /***************************************************************************** + * Color + **/ + --pst-color-on-background: #333333 !important; /*navbar bg-colour*/ + --pst-color-background: #ece9e5 !important; + + --pst-color-primary: #00a0af !important; /* headers */ + --pst-color-text-base: #49494a !important; + --pst-color-info: #009ddc !important; + --pst-color-success: 0, 168, 143; + --pst-color-warning: 250, 166, 52; + --pst-color-danger: 237, 23, 79; + + --pst-color-h1: var(--pst-color-primary) !important; + --pst-color-h2: var(--pst-color-primary) !important; + --pst-color-h3: #49494a !important; + --pst-color-h4: var(--pst-color-primary) !important; + --pst-color-h5: var(--pst-color-text-base); + --pst-color-h6: var(--pst-color-text-base); + --pst-color-paragraph: var(--pst-color-text-base); + --pst-color-link: #00a0af !important; /*links*/ + --pst-color-headerlink: #002d56 !important; + --pst-color-headerlink-hover: #0032fa !important; + --pst-color-inline-code: #ed174f !important; + + --pst-color-text-muted: #77757a !important ; /* Inactive sidebar links*/ + + --pst-color-active-navigation: red !important; /*#00A0Af !important;*/ + --pst-color-navbar-link: #ece9e5 !important; + + /***************************************************************************** + * Admonitions + **/ + --pst-color-admonition-default: var(--pst-color-info) !important; + --pst-color-admonition-note: var(--pst-color-info) !important; + + --pst-color-secondary: #00a0af !important; +} + +/***************************************************************************** +* 4Subsea tweaks +**/ +h1, +h2 { + color: var(--pst-color-h1); +} + +h1 { + font-size: 32px; +} +h2 { + font-size: 22px; +} + +h3 { + font-size: 18px; + font-weight: 700; +} + +/* Keep link color for visited links */ +a:visited { + color: var(--pst-color-link); +} + +/***************************************************************************** +* Admonitions +**/ + +.admonition, +div.admonition { + background-color: transparent; +} + +.table tbody tr:nth-child(odd) { + background-color: transparent; +} + +.table tbody tr:nth-child(even) { + background-color: transparent; +} + +/***************************************************************************** +* Header adjustments +**/ + +/* Let the inner header take full width */ +.bd-header__inner { + max-width: 100%; +} + +/* Distribute navigation items, see https://css-tricks.com/snippets/css/a-guide-to-flexbox/#aa-justify-content */ +.bd-header { + justify-content: space-between; +} + +/***************************************************************************** +* Logo and title +**/ + +/* Offset the logo to mimic the docs.4insight.io behaviour */ +.navbar-brand { + margin-left: 73px; + margin-top: 5px; + margin-right: 40px; /* Add some margin before coming elements*/ +} + +/* Fix logo image height*/ +.navbar-brand img { + height: 22px; +} + +.navbar-brand img:hover { + height: 32px; + border-top: transparent; + border-top-style: solid; + border-top-width: 2px; + padding-top: 3px; + border-bottom: var(--pst-color-primary); + border-bottom-style: solid; + border-bottom-width: 2px; + padding-bottom: 3px; +} + +/* Style the title next to logo */ +.navbar-brand p { + color: var(--pst-color-navbar-link); +} + +/* Turn of underline on hover */ +.navbar-brand:hover { + text-decoration: none; +} + +.logo__title { + font-size: var(--pst-font-size-logo); + padding-left: 4px; +} + +/* Make 4insight DOCUMENTATION take automatic width */ +.bd-header .navbar-header-items__start { + width: auto; +} + +/***************************************************************************** +* Navbar links +**/ + +/* General text color */ +.navbar-nav .nav-link { + color: var(--pst-color-navbar-link) !important; +} + +/* Style the underline on hover */ +.navbar-nav .nav-link:hover::after, +.navbar-nav .nav-link:focus::after { + text-decoration: underline; + text-decoration-thickness: 2px; + text-underline-offset: 3px; + text-decoration-color: var(--pst-color-link); +} + +/* For active/current page */ +.navbar-nav .nav-link.active::after { + color: var(--pst-color-navbar-link); + text-decoration: none; /* Remove underline for active link */ +} + +/* Set color for dropdown button */ +.bd-header ul.navbar-nav > li.nav-item.dropdown > .dropdown-toggle, +.bd-header ul.navbar-nav > li.nav-item.dropdown > .dropdown-toggle:hover { + color: var(--pst-color-navbar-link); + font-size: var(--pst-font-size-nav); +} + +/* Font size for navbar items */ +.bd-header .navbar-nav li { + font-size: var(--pst-font-size-nav); +} + +/* Set background color on hover for dropdown items */ +.bd-header ul.navbar-nav li a.nav-link.dropdown-item:hover { + background-color: transparent; + text-decoration: underline; + text-decoration-thickness: 2px; + text-underline-offset: 3px; + text-decoration-color: var(--pst-color-link); +} + +/* Color of navbar icons */ +html .pst-navbar-icon { + color: var(--pst-color-navbar-link); +} + +/***************************************************************************** +* Breadcrumb +**/ + +/* Styling for breadcrumb container */ +.breadcrumb { + height: var(--pst-header-height); + background-color: white; + font-size: var(--pst-font-size-breadcrumb); + padding-left: 16px; + padding-top: 10px; +} + +/* Breadcrumb list styling */ +ul.breadcrumb { + list-style: none; +} + +/* Remove default link styling */ +ul.breadcrumb li a { + text-decoration: none; +} + +/* Add underline effect on hover */ +ul.breadcrumb li a:hover { + color: var(--pst-color-link); + text-decoration: underline; + text-decoration-thickness: 1px; + text-underline-offset: 2px; +} + +/* Add '/' between breadcrumb items */ +ul.breadcrumb li + li:before { + padding: 5px; + color: var(--pst-color-text-base); + content: "/\00a0"; +} + +/* Keep the link color even if visited */ +ul.breadcrumb li a:visited { + color: var(--pst-color-link); +} diff --git a/docs/_static/empty b/docs/_static/empty deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/_static/favicon.png b/docs/_static/favicon.png new file mode 100644 index 00000000..899a801a Binary files /dev/null and b/docs/_static/favicon.png differ diff --git a/docs/_templates/breadcrumbs.html b/docs/_templates/breadcrumbs.html new file mode 100644 index 00000000..f5f5173a --- /dev/null +++ b/docs/_templates/breadcrumbs.html @@ -0,0 +1,19 @@ + \ No newline at end of file diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 00000000..8311430d --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,7 @@ +{% extends "!layout.html" %} + +{%- block docs_navbar %} +{{ super() }} +{# Insert breadcrumbs right after the navbar #} +{% include "breadcrumbs.html" %} +{%- endblock %} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index dbbf3b99..d9a3b4f1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,9 +3,15 @@ # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import inspect # Used in linkcode_resolve +import os +import sys from datetime import date from importlib import metadata +sys.path.insert(0, os.path.abspath("../")) +sys.path.insert(0, os.path.abspath("../src/")) + # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -14,6 +20,7 @@ author = "4Subsea" release = metadata.version("smsfusion") github_repo = "https://github.com/4Subsea/smsfusion-python/" +pypi_url = "https://pypi.org/project/smsfusion/" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -44,5 +51,69 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = "alabaster" +html_theme = "pydata_sphinx_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] +html_css_files = ["css/custom.css"] + +# Logo and favicon +html_favicon = "_static/favicon.png" +html_logo = "_static/4insight-logo.svg" + +html_theme_options = { + "logo": {"link": "http://docs.4insight.io", "text": "DOCUMENTATION"}, + "icon_links": [ + { + "name": "GitHub", + "url": github_repo, + "icon": "fab fa-github", + }, + { + "name": "PyPI", + "url": pypi_url, + "icon": "fas fa-box", + }, + ], + "navbar_end": [ + "search-button", # Includes the search icon + "navbar-icon-links", # Disables the light/dark mode toggle + ], + "navbar_persistent": [], # Removes the search field + "secondary_sidebar_items": [ + "page-toc", # Only show "On this page", hides the "Show sources" link + ], + "article_header_start": [], # Hides default breadcrumb +} + +html_context = { + "default_mode": "light", # Sets the default theme to light +} + + +def linkcode_resolve(domain, info): + + if domain != "py": + return None + if not info["module"]: + return None + + obj = sys.modules[info["module"]] + + for part in info["fullname"].split("."): + obj = getattr(obj, part) + + obj = inspect.unwrap(obj) + + # Inspect cannot find source file for properties + if isinstance(obj, property): + return None + + path = os.path.relpath(inspect.getfile(obj)) + src, lineno = inspect.getsourcelines(obj) + + path = f"{github_repo}blob/main/{path}#L{lineno}-L{lineno + len(src) - 1}" + + return path diff --git a/docs/user_guide/installation.rst b/docs/user_guide/installation.rst index 92f796bd..af453bc9 100644 --- a/docs/user_guide/installation.rst +++ b/docs/user_guide/installation.rst @@ -8,7 +8,7 @@ Head over to `Python.org`_ for instructions. Python version support ---------------------- -Officially Python 3.10, 3.11 and 3.12. We aim to support the three most recent major +Officially Python 3.11, 3.12 and 3.13. We aim to support the three most recent major versions. OS support diff --git a/pyproject.toml b/pyproject.toml index 9203be61..30d3c9f3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -61,6 +61,7 @@ complete = [ dependencies = [ "sphinx", "myst-parser", + "pydata-sphinx-theme", ] [tool.hatch.envs.docs.scripts]