diff --git a/.gitmodules b/.gitmodules index a97e786290..74422edfac 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,6 @@ [submodule "tests/spread/tools/snapd-testing-tools"] path = tests/spread/tools/snapd-testing-tools url = https://github.com/snapcore/snapd-testing-tools.git +[submodule "docs/sphinx-resources"] + path = docs/sphinx-resources + url = https://github.com/canonical/sphinx-docs-starter-pack.git diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 0fde76ea10..7c8204a4e8 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -4,6 +4,10 @@ --- version: 2 +submodules: + include: + - docs/sphinx-resources + build: os: ubuntu-22.04 tools: @@ -19,5 +23,5 @@ sphinx: python: install: - - requirements: docs/.sphinx/requirements.txt - requirements: docs/requirements.txt + - requirements: docs/sphinx-resources/.sphinx/requirements.txt diff --git a/docs/.sphinx/_static/custom.css b/docs/.sphinx/_static/custom.css deleted file mode 100644 index 9faf2a9c7c..0000000000 --- a/docs/.sphinx/_static/custom.css +++ /dev/null @@ -1,170 +0,0 @@ -/** 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; -} - -/* center align table cells with ":-:" */ -td.text-center { - text-align: center; -} - -/** 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); -} diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt deleted file mode 100644 index 95810152b3..0000000000 --- a/docs/.sphinx/requirements.txt +++ /dev/null @@ -1,10 +0,0 @@ -sphinx -sphinx-autobuild -sphinx-design -pyenchant -furo -sphinx-tabs -sphinx-reredirects -pyspelling -sphinx-copybutton -sphinx-pydantic diff --git a/docs/.sphinx/spellingcheck.yaml b/docs/.sphinx/spellingcheck.yaml deleted file mode 100644 index c9cb9a14c6..0000000000 --- a/docs/.sphinx/spellingcheck.yaml +++ /dev/null @@ -1,24 +0,0 @@ -matrix: -- name: rST files - aspell: - lang: en - d: en_GB - dictionary: - wordlists: - - .wordlist.txt - output: .sphinx/.wordlist.dic - sources: - - _build/**/*.html - pipeline: - - pyspelling.filters.html: - comments: false - attributes: - - title - - alt - ignores: - - code - - pre - - spellexception - - link - - title - - div.relatedlinks diff --git a/docs/Makefile b/docs/Makefile index 9e0b4fd50b..b4d3b468b7 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,11 +3,11 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS ?= +SPHINXOPTS ?= -q SPHINXBUILD ?= sphinx-build SOURCEDIR = . BUILDDIR = _build -VENV = .sphinx/venv/bin/activate +VENV = sphinx-resources/.sphinx/venv/bin/activate # Put it first so that "make" without argument is like "make help". @@ -16,8 +16,8 @@ help: install: @echo "... setting up virtualenv" - python3 -m venv .sphinx/venv - . $(VENV); pip install --upgrade -r .sphinx/requirements.txt -r requirements.txt + python3 -m venv sphinx-resources/.sphinx/venv + . $(VENV); pip install --upgrade -r sphinx-resources/.sphinx/requirements.txt -r requirements.txt @echo "\n" \ "--------------------------------------------------------------- \n" \ @@ -27,25 +27,36 @@ install: "* clean built doc files: make clean-doc \n" \ "* clean full environment: make clean \n" \ "* check spelling: make spelling \n" \ + "* check inclusive language: make woke \n" \ "--------------------------------------------------------------- \n" run: - . $(VENV); sphinx-autobuild -c . "$(SOURCEDIR)" "$(BUILDDIR)" + . $(VENV); sphinx-autobuild -c . -b html "$(SOURCEDIR)" "$(BUILDDIR)" html: - . $(VENV); $(SPHINXBUILD) -c . "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt + . $(VENV); $(SPHINXBUILD) -c . -b html "$(SOURCEDIR)" "$(BUILDDIR)" -w sphinx-resources/.sphinx/warnings.txt + +epub: + . $(VENV); $(SPHINXBUILD) -c . -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w sphinx-resources/.sphinx/warnings.txt serve: cd "$(BUILDDIR)"; python3 -m http.server 8000 clean: clean-doc - rm -rf .sphinx/venv rm -rf reference/commands + rm -rf sphinx-resources/.sphinx/venv clean-doc: git clean -fx "$(BUILDDIR)" spelling: html - . $(VENV) ; python3 -m pyspelling -c .sphinx/spellingcheck.yaml + . $(VENV) ; python3 -m pyspelling -c sphinx-resources/.sphinx/spellingcheck.yaml + +linkcheck: + . $(VENV) ; $(SPHINXBUILD) -c . -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" + +woke: + type woke >/dev/null 2>&1 || { snap install woke; exit 1; } + woke *.rst **/*.rst -c https://github.com/canonical-web-and-design/Inclusive-naming/raw/main/config.yml .PHONY: help Makefile diff --git a/docs/conf.py b/docs/conf.py index a35f297419..812413e6a8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,47 +21,145 @@ copyright = "%s, %s" % (datetime.date.today().year, author) release = snapcraft.__version__ +# Open Graph configuration - defines what is displayed in the website preview +ogp_site_url = "https://canonical-snapcraft.readthedocs-hosted.com" +ogp_site_name = project +ogp_image = "https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg" + +# Update with the favicon for your product +html_favicon = "sphinx-resources/.sphinx/_static/favicon.png" + +html_context = { + "discourse": "https://forum.snapcraft.io", + "github_url": "https://github.com/snapcore/snapcraft", + "github_version": "main", + "github_folder": "/docs/", + "github_issues": "enabled", +} + +# Used for related links - no need to change +if "discourse" in html_context: + html_context["discourse_prefix"] = html_context["discourse"] + "/t/" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + extensions = [ - "sphinx.ext.intersphinx", - "sphinx.ext.viewcode", - "sphinx.ext.coverage", - "sphinx.ext.doctest", "sphinx_design", + "sphinx_tabs.tabs", + "sphinx_reredirects", + "youtube-links", + "related-links", + "custom-rst-roles", + "terminal-output", "sphinx_copybutton", - "sphinx-pydantic", "sphinx.ext.autodoc", # Must be loaded after more_autodoc + "sphinxext.opengraph", + "myst_parser", ] -templates_path = ["_templates"] -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".sphinx"] +myst_enable_extensions = ["substitution", "deflist"] -show_authors = False +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "sphinx-resources"] rst_epilog = """ .. include:: /reuse/links.txt """ +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} + # Links to ignore when checking links linkcheck_ignore = ["http://127.0.0.1:8000"] +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +# Find the current builder +builder = "dirhtml" +if "-b" in sys.argv: + builder = sys.argv[sys.argv.index("-b") + 1] + +# Setting templates_path for epub makes the build fail +if builder == "dirhtml" or builder == "html": + templates_path = ["sphinx-resources/.sphinx/_templates"] + html_theme = "furo" -html_static_path = ["_static"] +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", + "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 = ["sphinx-resources/.sphinx/_static"] html_css_files = [ - "css/custom.css", + "custom.css", + "github_issue_links.css", ] -intersphinx_mapping = { - "python": ("https://docs.python.org/3", None), -} +html_js_files = [] +if "github_issues" in html_context and html_context["github_issues"]: + html_js_files.append("github_issue_links.js") -# Type hints configuration -set_type_checking_flag = True -typehints_fully_qualified = False -always_document_param_types = True -# Github config -github_username = "snapcore" -github_repository = "snapcraft" +# Set up redirects (https://documatt.gitlab.io/sphinx-reredirects/usage.html) +# For example: "explanation/old-name.html": "../how-to/prettify.html", +# redirects = {} def generate_cli_docs(nil): diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt index a7c690c861..bcc4554180 100644 --- a/docs/reuse/links.txt +++ b/docs/reuse/links.txt @@ -1,7 +1,18 @@ +.. _AppStream: https://www.freedesktop.org/software/appstream/docs/ +.. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en .. _Canonical website: https://canonical.com/ +.. _`Create a brand account`: https://snapcraft.io/docs/t/creating-snap-store-brand-accounts/6271 +.. _`Kernel connector`: https://www.kernel.org/doc/Documentation/connector/connector.txt +.. _managing-snap-configuration: https://snapcraft.io/docs/configuration-in-snaps +.. _`Markdown`: https://commonmark.org/help/ .. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/ +.. _ROS: https://www.ros.org/ +.. _setuptools: https://setuptools.readthedocs.io/en/latest/ +.. _`snap-channels`: https://snapcraft.io/docs/channels +.. _`Snap Store desktop app`: https://snapcraft.io/snap-store +.. _`Snap Store`: https://snapcraft.io/store .. _Sphinx reStructuredText Primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html -.. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en -.. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs -.. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs -.. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/ +.. _`the Snapcraft forum`: https://forum.snapcraft.io +.. _`Ubuntu Core`: https://ubuntu.com/core/ +.. _vscode: https://code.visualstudio.com/ +.. _`YAML specification`: https://yaml.org/spec/ diff --git a/docs/sphinx-resources b/docs/sphinx-resources new file mode 160000 index 0000000000..5483aa25f5 --- /dev/null +++ b/docs/sphinx-resources @@ -0,0 +1 @@ +Subproject commit 5483aa25f548344fe3e45a1ed13450de93f0f3ef diff --git a/pyproject.toml b/pyproject.toml index ead6badb2a..df45608a51 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,6 +3,7 @@ extend-exclude = ''' /( | snapcraft_legacy | tools + | docs/sphinx-resources )/ ''' # Targeting future versions as well so we don't have black reformatting code diff --git a/tox.ini b/tox.ini index 6158f7f1da..369b3c38c7 100644 --- a/tox.ini +++ b/tox.ini @@ -133,7 +133,7 @@ commands_pre = mypy: mkdir -p .mypy_cache commands = pyright: pyright {posargs} - mypy: mypy --install-types --non-interactive . + mypy: mypy --install-types --non-interactive --exclude 'docs/sphinx-resources/conf.py' . [testenv:format-{black,ruff,codespell}] description = Automatically format source code @@ -154,14 +154,16 @@ env_dir = {work_dir}/docs runner = ignore_env_name_mismatch deps = sphinx-lint==0.6.7 - -r{tox_root}/requirements.txt - -r{tox_root}/docs/.sphinx/requirements.txt + -r{tox_root}/docs/requirements.txt [testenv:build-docs] description = Build sphinx documentation base = docs allowlist_externals = bash -commands_pre = bash -c 'if [[ ! -e docs ]];then echo "No docs directory. Run `tox run -e sphinx-quickstart` to create one.;";return 1;fi' +commands_pre = + bash -c 'if [[ ! -e docs ]];then echo "No docs directory. Run `tox run -e sphinx-quickstart` to create one.;";return 1;fi' + bash -c 'git submodule update --init docs/sphinx-resources' + bash -c 'pip install -r{tox_root}/docs/sphinx-resources/.sphinx/requirements.txt' # "-W" is to treat warnings as errors commands = sphinx-build {posargs:-b html} -W {tox_root}/docs {tox_root}/docs/_build @@ -173,5 +175,5 @@ commands = sphinx-autobuild {posargs:-b html --open-browser --port 8080} -W --wa [testenv:lint-docs] description = Lint the documentation with sphinx-lint base = docs -commands = sphinx-lint --ignore docs/_build -e all {posargs} docs/ +commands = sphinx-lint --ignore docs/_build --ignore docs/sphinx-resources -e all {posargs} docs/ labels = lint