diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 000000000..cad94b74c --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,189 @@ +/** Fix the font weight (300 for normal, 400 for slightly bold) **/ + +div.page, h1, h2, h3, h4, h5, h6, .sidebar-tree .current-page>.reference, button, input, optgroup, select, textarea, th.head { + font-weight: 300 +} + +.toc-tree li.scroll-current>.reference, dl.glossary dt, dl.simple dt, dl:not([class]) dt { + font-weight: 400; +} + +/** Table styling **/ + +th.head { + text-transform: uppercase; + font-size: var(--font-size--small); +} + +table.docutils { + border: 0; + box-shadow: none; + width:100%; +} + +table.docutils td, table.docutils th, table.docutils td:last-child, table.docutils th:last-child, table.docutils td:first-child, table.docutils th:first-child { + border-right: none; + border-left: none; +} + +/* Allow to centre text horizontally in table data cells */ +table.align-center { + text-align: center !important; +} + +/** No rounded corners **/ + +.admonition, code.literal, .sphinx-tabs-tab, .sphinx-tabs-panel, .highlight { + border-radius: 0; +} + +/** Admonition styling **/ + +.admonition { + border-top: 1px solid #d9d9d9; + border-right: 1px solid #d9d9d9; + border-bottom: 1px solid #d9d9d9; +} + +/** Color for the "copy link" symbol next to headings **/ + +a.headerlink { + color: var(--color-brand-primary); +} + +/** Line to the left of the current navigation entry **/ + +.sidebar-tree li.current-page { + border-left: 2px solid var(--color-brand-primary); +} + +/** Some tweaks for issue #16 **/ + +[role="tablist"] { + border-bottom: 1px solid var(--color-sidebar-item-background--hover); +} + +.sphinx-tabs-tab[aria-selected="true"] { + border: 0; + border-bottom: 2px solid var(--color-brand-primary); + background-color: var(--color-sidebar-item-background--current); + font-weight:300; +} + +.sphinx-tabs-tab{ + color: var(--color-brand-primary); + font-weight:300; +} + +.sphinx-tabs-panel { + border: 0; + border-bottom: 1px solid var(--color-sidebar-item-background--hover); + background: var(--color-background-primary); +} + +button.sphinx-tabs-tab:hover { + background-color: var(--color-sidebar-item-background--hover); +} + +/** Custom classes to fix scrolling in tables by decreasing the + font size or breaking certain columns. + Specify the classes in the Markdown file with, for example: + ```{rst-class} break-col-4 min-width-4-8 + ``` +**/ + +table.dec-font-size { + font-size: smaller; +} +table.break-col-1 td.text-left:first-child { + word-break: break-word; +} +table.break-col-4 td.text-left:nth-child(4) { + word-break: break-word; +} +table.min-width-1-15 td.text-left:first-child { + min-width: 15em; +} +table.min-width-4-8 td.text-left:nth-child(4) { + min-width: 8em; +} + +/** Underline for abbreviations **/ + +abbr[title] { + text-decoration: underline solid #cdcdcd; +} + +/** Use the same style for right-details as for left-details **/ +.bottom-of-page .right-details { + font-size: var(--font-size--small); + display: block; +} + +/** Version switcher */ +button.version_select { + color: var(--color-foreground-primary); + background-color: var(--color-toc-background); + padding: 5px 10px; + border: none; +} + +.version_select:hover, .version_select:focus { + background-color: var(--color-sidebar-item-background--hover); +} + +.version_dropdown { + position: relative; + display: inline-block; + text-align: right; + font-size: var(--sidebar-item-font-size); +} + +.available_versions { + display: none; + position: absolute; + right: 0px; + background-color: var(--color-toc-background); + box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2); + z-index: 11; +} + +.available_versions a { + color: var(--color-foreground-primary); + padding: 12px 16px; + text-decoration: none; + display: block; +} + +.available_versions a:hover {background-color: var(--color-sidebar-item-background--current)} + +.show {display:block;} + +/** Fix for nested numbered list - the nested list is lettered **/ +ol.arabic ol.arabic { + list-style: lower-alpha; +} + +/** Make expandable sections look like links **/ +details summary { + color: var(--color-link); +} + +/** Fix the styling of the version box for readthedocs **/ + +#furo-readthedocs-versions .rst-versions, #furo-readthedocs-versions .rst-current-version, #furo-readthedocs-versions:focus-within .rst-current-version, #furo-readthedocs-versions:hover .rst-current-version { + background: var(--color-sidebar-item-background--hover); +} + +.rst-versions .rst-other-versions dd a { + color: var(--color-link); +} + +#furo-readthedocs-versions:focus-within .rst-current-version .fa-book, #furo-readthedocs-versions:hover .rst-current-version .fa-book, .rst-versions .rst-other-versions { + color: var(--color-sidebar-link-text); +} + +.rst-versions .rst-current-version { + color: var(--color-version-popup); + font-weight: bolder; +} diff --git a/docs/_static/favicon.png b/docs/_static/favicon.png new file mode 100644 index 000000000..c7109908f Binary files /dev/null and b/docs/_static/favicon.png differ diff --git a/docs/_static/github_issue_links.css b/docs/_static/github_issue_links.css new file mode 100644 index 000000000..af4be86ce --- /dev/null +++ b/docs/_static/github_issue_links.css @@ -0,0 +1,24 @@ +.github-issue-link-container { + padding-right: 0.5rem; +} +.github-issue-link { + font-size: var(--font-size--small); + font-weight: bold; + background-color: #DD4814; + padding: 13px 23px; + text-decoration: none; +} +.github-issue-link:link { + color: #FFFFFF; +} +.github-issue-link:visited { + color: #FFFFFF +} +.muted-link.github-issue-link:hover { + color: #FFFFFF; + text-decoration: underline; +} +.github-issue-link:active { + color: #FFFFFF; + text-decoration: underline; +} diff --git a/docs/_static/github_issue_links.js b/docs/_static/github_issue_links.js new file mode 100644 index 000000000..980609cd0 --- /dev/null +++ b/docs/_static/github_issue_links.js @@ -0,0 +1,26 @@ +window.onload = function() { + const link = document.createElement("a"); + link.classList.add("muted-link"); + link.classList.add("github-issue-link"); + link.text = "Give feedback"; + link.href = ( + github_url + + "/issues/new?" + + "title=docs%3A+TYPE+YOUR+QUESTION+HERE" + + "&body=*Please describe the question or issue you're facing with " + + `"${document.title}"` + + ".*" + + "%0A%0A%0A%0A%0A" + + "---" + + "%0A" + + `*Reported+from%3A+${location.href}*` + ); + link.target = "_blank"; + + const div = document.createElement("div"); + div.classList.add("github-issue-link-container"); + div.append(link) + + const container = document.querySelector(".article-container > .content-icon-container"); + container.prepend(div); +}; diff --git a/docs/_templates/base.html b/docs/_templates/base.html new file mode 100644 index 000000000..62ffe6b8c --- /dev/null +++ b/docs/_templates/base.html @@ -0,0 +1,7 @@ +{% extends "furo/base.html" %} + +{% block theme_scripts %} + +{% endblock theme_scripts %} diff --git a/docs/_templates/footer.html b/docs/_templates/footer.html new file mode 100644 index 000000000..759448687 --- /dev/null +++ b/docs/_templates/footer.html @@ -0,0 +1,90 @@ +{# ru-fu: copied from Furo, with modifications as stated below #} + +
+ {% if next -%} + +
+
+ {{ _("Next") }} +
+
{{ next.title }}
+
+ + + {%- endif %} + {% if prev -%} + + +
+
+ {{ _("Previous") }} +
+ {% if prev.link == pathto(master_doc) %} +
{{ _("Home") }}
+ {% else %} +
{{ prev.title }}
+ {% endif %} +
+ + {%- endif %} +
+
+
+ {%- if show_copyright %} +
+ {%- if hasdoc('copyright') %} + {% trans path=pathto('copyright'), copyright=copyright|e -%} + Copyright © {{ copyright }} + {%- endtrans %} + {%- else %} + {% trans copyright=copyright|e -%} + Copyright © {{ copyright }} + {%- endtrans %} + {%- endif %} +
+ {%- endif %} + + {# ru-fu: removed "Made with" #} + + {%- if last_updated -%} +
+ {% trans last_updated=last_updated|e -%} + Last updated on {{ last_updated }} + {%- endtrans -%} +
+ {%- endif %} + + {%- if show_source and has_source and sourcename %} +
+ Show source +
+ {%- endif %} +
+
+ + {# ru-fu: replaced RTD icons with our links #} + + {% if discourse %} +
+ Ask a question on Discourse +
+ {% endif %} + + {% if github_url and github_version and github_folder %} + + {% if github_issues %} +
+ Open a GitHub issue for this page +
+ {% endif %} + +
+ Edit this page on GitHub +
+ {% endif %} + + +
+
+ diff --git a/docs/_templates/page.html b/docs/_templates/page.html new file mode 100644 index 000000000..ede3495c8 --- /dev/null +++ b/docs/_templates/page.html @@ -0,0 +1,44 @@ +{% extends "furo/page.html" %} + +{% block footer %} + {% include "footer.html" %} +{% endblock footer %} + +{% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %} + {% set furo_hide_toc_orig = furo_hide_toc %} + {% set furo_hide_toc=false %} +{% endif %} + +{% block right_sidebar %} +
+ {% if not furo_hide_toc_orig %} +
+ + {{ _("Contents") }} + +
+
+
+ {{ toc }} +
+
+ {% endif %} + {% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %} +
+ + Related links + +
+
+
+ {% if meta.discourse and discourse_prefix %} + {{ discourse_links(meta.discourse) }} + {% endif %} + {% if meta.relatedlinks %} + {{ related_links(meta.relatedlinks) }} + {% endif %} +
+
+ {% endif %} +
+{% endblock right_sidebar %} diff --git a/docs/conf.py b/docs/conf.py index 1d48f0387..a78c70af3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,12 +3,32 @@ # For a full list of options see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +# NOTE: a fair bit of this is copied from: +# https://github.com/canonical/sphinx-docs-starter-pack/blob/main/conf.py + # -- Path setup -------------------------------------------------------------- -from pathlib import Path +import furo +import furo.navigation +import pathlib import sys -sys.path.insert(0, str(Path(__file__).parent.parent)) + +sys.path.insert(0, str(pathlib.Path(__file__).parent.parent)) + + +# Furo patch to get local TOC to show in sidebar (as sphinx-rtd-theme did) +# See https://github.com/pradyunsg/furo/blob/490527b2aef00b1198770c3389a1979911ee1fcb/src/furo/__init__.py#L115-L128 + +_old_compute_navigation_tree = furo._compute_navigation_tree + +def _compute_navigation_tree(context): + tree_html = _old_compute_navigation_tree(context) + if not tree_html and context.get("toc"): + tree_html = furo.navigation.get_navigation_tree(context["toc"]) + return tree_html + +furo._compute_navigation_tree = _compute_navigation_tree # -- Project information ----------------------------------------------------- @@ -17,6 +37,16 @@ copyright = '2019-2023, Canonical Ltd.' author = 'Canonical Ltd' +html_favicon = "_static/favicon.png" + +html_context = { + "discourse": "https://discourse.charmhub.io/", + "discourse_prefix": "https://discourse.charmhub.io/t/", + "github_url": "https://github.com/canonical/operator", + "github_version": "main", + "github_folder": "/docs/", + "github_issues": "enabled", +} # -- General configuration --------------------------------------------------- @@ -42,12 +72,29 @@ # ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', 'sphinx.ext.napoleon', 'sphinx.ext.todo', 'sphinx.ext.viewcode', - 'sphinx.ext.intersphinx', + + 'custom-rst-roles', + 'related-links', + 'sphinx_copybutton', + 'sphinx_design', + 'sphinx_tabs.tabs', ] +rst_epilog = """ +.. _Canonical website: https://canonical.com/ +.. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/ +.. _Sphinx reStructuredText Primer: https://tinyurl.com/rstprimer +.. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en +""" + +source_suffix = { + '.rst': 'restructuredtext', +} + # The document name of the “master” document, that is, the document # that contains the root toctree directive. master_doc = 'index' @@ -63,15 +110,81 @@ # -- Options for HTML output ------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'sphinx_rtd_theme' # 'alabaster' +# Find the current builder +builder = "dirhtml" +if '-b' in sys.argv: + builder = sys.argv[sys.argv.index('-b')+1] + +html_theme = 'furo' +html_last_updated_fmt = "" +html_permalinks_icon = "¶" +html_theme_options = { + "light_css_variables": { + "color-sidebar-background-border": "none", + "font-stack": "Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif", + "font-stack--monospace": "Ubuntu Mono, Consolas, Monaco, Courier, monospace", + "color-foreground-primary": "#111", + "color-foreground-secondary": "var(--color-foreground-primary)", + "color-foreground-muted": "#333", + "color-background-secondary": "#FFF", + "color-background-hover": "#f2f2f2", + "color-brand-primary": "#111", + "color-brand-content": "#06C", + # NOTE: this looks horrible -- commented out + #"color-api-background": "#cdcdcd", + "color-inline-code-background": "rgba(0,0,0,.03)", + "color-sidebar-link-text": "#111", + "color-sidebar-item-background--current": "#ebebeb", + "color-sidebar-item-background--hover": "#f2f2f2", + "toc-font-size": "var(--font-size--small)", + "color-admonition-title-background--note": "var(--color-background-primary)", + "color-admonition-title-background--tip": "var(--color-background-primary)", + "color-admonition-title-background--important": "var(--color-background-primary)", + "color-admonition-title-background--caution": "var(--color-background-primary)", + "color-admonition-title--note": "#24598F", + "color-admonition-title--tip": "#24598F", + "color-admonition-title--important": "#C7162B", + "color-admonition-title--caution": "#F99B11", + "color-highlighted-background": "#EbEbEb", + "color-link-underline": "var(--color-background-primary)", + "color-link-underline--hover": "var(--color-background-primary)", + "color-version-popup": "#772953" + }, + "dark_css_variables": { + "color-foreground-secondary": "var(--color-foreground-primary)", + "color-foreground-muted": "#CDCDCD", + "color-background-secondary": "var(--color-background-primary)", + "color-background-hover": "#666", + "color-brand-primary": "#fff", + "color-brand-content": "#06C", + "color-sidebar-link-text": "#f7f7f7", + "color-sidebar-item-background--current": "#666", + "color-sidebar-item-background--hover": "#333", + "color-admonition-background": "transparent", + "color-admonition-title-background--note": "var(--color-background-primary)", + "color-admonition-title-background--tip": "var(--color-background-primary)", + "color-admonition-title-background--important": "var(--color-background-primary)", + "color-admonition-title-background--caution": "var(--color-background-primary)", + "color-admonition-title--note": "#24598F", + "color-admonition-title--tip": "#24598F", + "color-admonition-title--important": "#C7162B", + "color-admonition-title--caution": "#F99B11", + "color-highlighted-background": "#666", + "color-link-underline": "var(--color-background-primary)", + "color-link-underline--hover": "var(--color-background-primary)", + "color-version-popup": "#F29879" + }, +} + +html_static_path = ['_static'] +html_css_files = [ + 'custom.css', + 'github_issue_links.css', +] -# 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 = [] +html_js_files = [] +if "github_issues" in html_context and html_context["github_issues"]: + html_js_files.append('github_issue_links.js') # -- Options for sphinx.ext.todo --------------------------------------------- diff --git a/docs/requirements.in b/docs/requirements.in index 2e1cff85b..f500c5e51 100644 --- a/docs/requirements.in +++ b/docs/requirements.in @@ -1,3 +1,7 @@ -r ../requirements.txt -sphinx==6.2.1 # Latest sphinx_rtd_theme doesn't yet support sphinx 7.x -sphinx_rtd_theme==1.2.1 +sphinx==6.2.1 +sphinx-design +furo +sphinx-tabs +lxd-sphinx-extensions +sphinx-copybutton diff --git a/docs/requirements.txt b/docs/requirements.txt index 911328e6a..949cb5172 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,23 +1,29 @@ alabaster==0.7.13 Babel==2.12.1 +beautifulsoup4==4.12.2 certifi==2023.5.7 charset-normalizer==3.1.0 docutils==0.18.1 +furo==2023.5.20 idna==3.4 imagesize==1.4.1 Jinja2==3.1.2 +lxd-sphinx-extensions==0.0.7 MarkupSafe==2.1.2 packaging==23.1 Pygments==2.15.1 PyYAML==6.0 requests==2.31.0 snowballstemmer==2.2.0 +soupsieve==2.4.1 Sphinx==6.2.1 -sphinx-rtd-theme==1.2.1 +sphinx-basic-ng==1.0.0b1 +sphinx-copybutton==0.5.2 +sphinx-tabs==3.4.1 +sphinx_design==0.4.1 sphinxcontrib-applehelp==1.0.4 sphinxcontrib-devhelp==1.0.2 sphinxcontrib-htmlhelp==2.0.1 -sphinxcontrib-jquery==4.1 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==1.0.3 sphinxcontrib-serializinghtml==1.1.5