diff --git a/CHANGELOG.md b/CHANGELOG.md index a3d93b90..b54e1c9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # sphinx-stack changelog -## Upcoming +## 3.0 * Make removed URL check redirect-aware and add support for reusable workflow contexts * Exclude utility directories from builds and checks @@ -11,12 +11,15 @@ * Update and pin CI actions * Remove extensions deprecated in 2.0 * Replace remote documentation checks in CI +* Add default support for the Ulwazi theme ### Changed -* `docs/conf.py` [#610](https://github.com/canonical/sphinx-stack/pull/610), [#634](https://github.com/canonical/sphinx-stack/pull/634), [#646](https://github.com/canonical/sphinx-stack/pull/646) +* `docs/conf.py` [#610](https://github.com/canonical/sphinx-stack/pull/610), [#634](https://github.com/canonical/sphinx-stack/pull/634), [#646](https://github.com/canonical/sphinx-stack/pull/646), [#650](https://github.com/canonical/sphinx-stack/pull/650) * `docs/Makefile` [#605](https://github.com/canonical/sphinx-stack/pull/605), [#610](https://github.com/canonical/sphinx-stack/pull/610), [#627](https://github.com/canonical/sphinx-stack/pull/627), [#628](https://github.com/canonical/sphinx-stack/pull/628) -* `docs/requirements.txt` [#634](https://github.com/canonical/sphinx-stack/pull/634), [#646](https://github.com/canonical/sphinx-stack/pull/646) +* `docs/requirements.txt` [#634](https://github.com/canonical/sphinx-stack/pull/634), [#646](https://github.com/canonical/sphinx-stack/pull/646), [#650](https://github.com/canonical/sphinx-stack/pull/650) +* `docs/_templates/header.html` [#650](https://github.com/canonical/sphinx-stack/pull/650) +* `docs/_templates/footer.html` [#650](https://github.com/canonical/sphinx-stack/pull/650) * `README.md` [#603](https://github.com/canonical/sphinx-stack/pull/603) * `.github/workflows/automatic-doc-checks.yml` [#642](https://github.com/canonical/sphinx-stack/pull/642) * `.github/workflows/cla-check.yml` [#606](https://github.com/canonical/sphinx-stack/pull/606), [#648](https://github.com/canonical/sphinx-stack/pull/648) diff --git a/docs/_templates/footer.html b/docs/_templates/footer.html deleted file mode 100644 index e1d10889..00000000 --- a/docs/_templates/footer.html +++ /dev/null @@ -1,103 +0,0 @@ - -
-
- {%- if show_copyright %} - - {%- endif %} - {%- if license and license.name -%} - {%- if license.url -%} -
- This page is licensed under {{ license.name }} -
- {%- else -%} -
- This page is licensed under {{ license.name }} -
- {%- endif -%} - {%- endif -%} - - {# mod: 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 %} - - {%- endif %} -
-
- {% if has_contributor_listing and display_contributors and pagename and page_source_suffix %} - {% set contributors = get_contributors_for_file(pagename, page_source_suffix) %} - {% if contributors %} - {% if contributors | length > 1 %} - Thanks to the {{ contributors |length }} contributors! - {% else %} - Thanks to our contributor! - {% endif %} -
- - {% endif %} - {% endif %} -
-
Manage your tracker settings
-
\ No newline at end of file diff --git a/docs/_templates/header.html b/docs/_templates/header.html deleted file mode 100644 index 9ee3c77d..00000000 --- a/docs/_templates/header.html +++ /dev/null @@ -1,72 +0,0 @@ - \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 49ee75fd..7b021b9c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -11,17 +11,16 @@ # A complete list of built-in Sphinx configuration values: # https://www.sphinx-doc.org/en/master/usage/configuration.html # -# The Sphinx Stack uses the Canonical Sphinx theme to keep all documentation consistent -# and on brand: -# https://github.com/canonical/canonical-sphinx +# The Sphinx Stack uses the Ulwazi theme: +# https://github.com/canonical/ulwazi ####################### # Project information # ####################### # Project name -# TODO: Update with the official name of your project or product (e.g., "Ubuntu Server") -project = "Project" +# TODO: Update with the official name of your project (e.g., "LXD documentation") +project = "Project documentation" # Author name; used in the default copyright statement in the page footer author = "Canonical Ltd." @@ -29,9 +28,8 @@ # The year in the copyright statement copyright = f"{datetime.date.today().year}" -# Sidebar documentation title -# To disable the title, set it to an empty string. -html_title = project + " documentation" +# String appended to the title of individual HTML pages +html_title = project # Documentation website URL ogp_site_url = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") @@ -48,45 +46,28 @@ # TODO: To customise the favicon, uncomment and update the next line. # html_favicon = "_static/favicon.png" -# Dictionary of values to pass into the Sphinx context for all pages: -# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_context +# The theme for the HTML output +html_theme = "ulwazi" + +# Dictionary of values to pass into every page's template. html_context = { - # Product page URL; can be different from product docs URL - # TODO: Change to your product website URL, dropping the 'https://' prefix (e.g., - # 'ubuntu.com/lxd'). If there's no such website, remove the {{ product_page }} - # link from the _templates/header.html file. - "product_page": "", - # Product tag image; the orange part of your logo, shown in the page header - # TODO: To add a tag image, uncomment and update as needed. - # 'product_tag': '_static/tag.png', - # Your Discourse instance URL - # TODO: Change to your Discourse instance URL or leave empty. + # Community links for the 'Resources' dropdown menu. + # TODO: Add community links; empty values hide individual links. "discourse": "", - # Your Mattermost channel URL - # TODO: Change to your Mattermost channel URL or leave empty. "mattermost": "", - # Your Matrix channel URL - # TODO: Change to your Matrix channel URL or leave empty. "matrix": "", - # Your documentation GitHub repository URL If set, links for viewing the - # documentation source files and creating GitHub issues are added at the bottom of - # each page. - # TODO: Change to your documentation GitHub repository URL or leave empty. "github_url": "", - # Docs branch in the repo; used in links for viewing the source files - "repo_default_branch": "main", - # Docs location in the repo; used in links for viewing the source files - "repo_folder": "/docs/", - # TODO: To enable or disable the Previous / Next buttons at the bottom of pages - # Valid options: none, prev, next, both - # "sequential_nav": "", - # TODO: To enable listing contributors on individual pages, set to True - "display_contributors": False, - # Required for feedback button - "github_issues": "enabled", - # Passes the top-level 'author' value to the theme + # Feedback and edit/view links require a valid `github_url`. + # TODO: Set to False to hide feedback and page controls. + "feedback": True, + # Brand configuration for the leftmost entry in the banner + # TODO: If your project falls under a different product page, update the title, URL, + # and logo if necessary. + "logo_title": "Canonical", + "logo_link_URL": "https://canonical.com", + "logo_img_URL": "https://assets.ubuntu.com/v1/82818827-CoF_white.svg", + # License information to be rendered in the footer "author": author, - # Documentation license information "license": { # TODO: Specify your project's license. # For the name, we recommend using the standard shorthand identifier from @@ -97,22 +78,6 @@ }, } -# TODO: To enable the edit button on pages, uncomment and change the link to a -# public repository on GitHub or Launchpad. Any of the following link domains -# are accepted: -# - https://github.com/example-org/example" -# - https://launchpad.net/example -# - https://git.launchpad.net/example -# -# html_theme_options = { -# 'source_edit_link': 'https://github.com/canonical/sphinx-stack', -# } - -# Project slug -# TODO: If your documentation is hosted on https://documentation.ubuntu.com/, -# uncomment and set to the RTD slug. -# slug = '' - ####################### # Sitemap configuration: https://sphinx-sitemap.readthedocs.io/ ####################### @@ -140,7 +105,6 @@ ################################ # html_static_path = ["_static"] -# templates_path = ["_templates"] ############# # Redirects # @@ -208,25 +172,18 @@ # Configuration extras # ######################## -# Custom MyST syntax extensions; see -# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html -# NOTE: By default, the following MyST extensions are enabled: -# - substitution -# - deflist -# - linkify -# myst_enable_extensions = set() - # Custom Sphinx extensions; see # https://www.sphinx-doc.org/en/master/usage/extensions/index.html extensions = [ - "canonical_sphinx", - "notfound.extension", + "ulwazi", + "myst_parser", "sphinx_design", "sphinx_rerediraffe", "sphinxcontrib.jquery", "sphinxext.opengraph", "sphinx_config_options", "sphinx_llm.txt", + "sphinx_modern_pdf_style", "sphinx_related_links", "sphinx_roles", "sphinx_terminal", @@ -244,36 +201,38 @@ ] # Adds custom CSS files, located remotely or in 'html_static_path'. -# html_css_files = [ -# "https://assets.ubuntu.com/v1/d86746ef-cookie_banner.css", -# ] +html_css_files = [ + "https://assets.ubuntu.com/v1/d86746ef-cookie_banner.css", +] # Adds custom JavaScript files, located remotely or in 'html_static_path'. -# html_js_files = [ -# "https://assets.ubuntu.com/v1/287a5e8f-bundle.js", -# ] +html_js_files = [ + "https://assets.ubuntu.com/v1/287a5e8f-bundle.js", +] # Appends extra markup to the end of every document written in reST # rst_epilog = """ # """ -# Feedback button at the top; enabled by default -# TODO: Disable the button if your project is unsuitable for public feedback. -# disable_feedback_button = True +# Project slug +# TODO: Set to your project slug. If your docs were hosted at +# https://canonical.com/juju/docs/ops, you'd set this to "juju/docs/ops". +slug = "" + +# Apply modern PDF styling and configuration +set_modern_pdf_config = True # Your manpage URL # TODO: To enable manpage links, uncomment and replace {codename} with required # release, preferably an LTS release (e.g. noble). Do *not* substitute # {section} or {page}; these will be replaced by sphinx at build time # -# NOTE: If set, adding ':manpage:' to an .rst file -# adds a link to the corresponding man section at the bottom of the page. +# If set, the :manpage: role creates an inline link to the manual page. # manpages_url = 'https://manpages.ubuntu.com/manpages/{codename}/en/' + \ # 'man{section}/{page}.{section}.html' # Specifies a reST snippet to be prepended to each .rst file # This defines a :center: role that centers table cell content. -# This defines a :h2: role that styles content for use with PDF generation. rst_prolog = """ .. role:: center :class: align-center diff --git a/docs/requirements.txt b/docs/requirements.txt index 5928d4ef..87f9825c 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,11 +1,10 @@ -# Canonical theme (still needed for Furo theme and custom templates) -canonical-sphinx~=0.7 +# Ulwazi theme +ulwazi~=1.0 # Extensions previously auto-loaded by canonical-sphinx myst-parser~=4.0 # v5.0.0 causes version conflicts sphinx-autobuild==2024.10.3 sphinx-design==0.6.1 -sphinx-notfound-page~=1.1 sphinxcontrib-jquery~=4.1 sphinxext-opengraph~=0.13 sphinx-rerediraffe~=0.1 @@ -22,6 +21,7 @@ packaging~=26.3 sphinxcontrib-svg2pdfconverter[CairoSVG]~=2.1 sphinx-sitemap~=2.9 sphinx-llm~=1.1 +sphinx-modern-pdf-style~=0.1 # Vale dependencies rst2html