From 116822abbe166e061ebe35474663c7d722af4502 Mon Sep 17 00:00:00 2001 From: Tiago Nobrega Date: Fri, 26 Apr 2024 15:09:01 -0300 Subject: [PATCH] docs: use canonical-sphinx This requires updating requirements-doc.txt via: 1) adding 'canonical-sphinx' as a dep in setup.cfg; 2) creating an env with '.[doc]' 3) freezing the env via "pip list --format=freeze > requirements-doc.txt" --- .readthedocs.yaml | 14 --- Makefile | 8 +- docs/_static/.gitempty | 0 docs/_static/css/custom.css | 3 - docs/conf.py | 221 +++++++----------------------------- requirements-doc.txt | 68 +++++++---- setup.cfg | 8 +- 7 files changed, 90 insertions(+), 232 deletions(-) delete mode 100644 docs/_static/.gitempty delete mode 100644 docs/_static/css/custom.css diff --git a/.readthedocs.yaml b/.readthedocs.yaml index e48636709..8398dfe19 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -9,12 +9,6 @@ build: os: ubuntu-22.04 tools: python: "3.10" - jobs: - post_checkout: - - git submodule update --init -- docs/sphinx-starter-pack - - make preparedocs - post_install: - - ./tools/mkdoclinks.sh # Build documentation in the docs/ directory with Sphinx sphinx: @@ -22,14 +16,6 @@ sphinx: builder: dirhtml fail_on_warning: true -# Build documentation with MkDocs -# mkdocs: -# configuration: mkdocs.yml - -# Optionally build your docs in additional formats such as PDF -formats: - - pdf - # Optionally set the version of Python # and requirements required to build your docs python: diff --git a/Makefile b/Makefile index 1bd0323bb..56b21a468 100644 --- a/Makefile +++ b/Makefile @@ -38,14 +38,8 @@ coverage: ## Run pytest with coverage report. coverage report -m coverage html -.PHONY: preparedocs -preparedocs: ## move file from the sphinx-starter-pack to docs folder - cp docs/sphinx-starter-pack/.sphinx/_static/* docs/_static - mkdir -p docs/_templates - cp -R docs/sphinx-starter-pack/.sphinx/_templates/* docs/_templates - .PHONY: installdocs -installdocs: preparedocs ## install documentation dependencies. +installdocs: $(MAKE) -C docs install .PHONY: docs diff --git a/docs/_static/.gitempty b/docs/_static/.gitempty deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css deleted file mode 100644 index 71cc44b82..000000000 --- a/docs/_static/css/custom.css +++ /dev/null @@ -1,3 +0,0 @@ -.log-snippets { - color: rgb(141, 141, 141); -} diff --git a/docs/conf.py b/docs/conf.py index 26216c1b1..c524a37d2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,5 +1,4 @@ -# -# Copyright 2021 Canonical Ltd. +# Copyright 2023-2024 Canonical Ltd. # # This program is free software; you can redistribute it and/or # modify it under the terms of the GNU Lesser General Public @@ -15,19 +14,7 @@ # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, make it absolute. -# - +import datetime import os import pathlib import sys @@ -37,75 +24,62 @@ project_dir = pathlib.Path("..").resolve() sys.path.insert(0, str(project_dir.absolute())) -import rockcraft # noqa: E402 - -# -- Project information ----------------------------------------------------- - project = "Rockcraft" -copyright = "2021, Canonical Ltd." -author = "Canonical Ltd." +author = "Canonical Group Ltd" -# The full version, including alpha/beta/rc tags -release = rockcraft.__version__ -if ".post" in release: - # The commit hash in the dev release version confuses the spellchecker - release = release[0 : release.find(".post")] +copyright = "2022-%s, %s" % (datetime.date.today().year, author) -# Update with the favicon for your product -html_favicon = "_static/favicon.png" +# region Configuration for canonical-sphinx +ogp_site_url = "https://canonical-rockcraft.readthedocs-hosted.com/" +ogp_site_name = project html_context = { - # Change to the link to your product website (without "https://") "product_page": "github.com/canonical/rockcraft", - # Add your product tag to ".sphinx/_static" and change the path - # here (start with "_static"), default is the circle of friends - "product_tag": "_static/tag.png", - # Change to the discourse instance you want to be able to link to - # (use an empty value if you don't want to link) "discourse": "https://discourse.ubuntu.com/c/rocks/117", - # Change to the GitHub info for your project "github_url": "https://github.com/canonical/rockcraft", - # Change to the branch for this version of the documentation - "github_version": "main", - # Change to the folder that contains the documentation (usually "/" or "/docs/") - "github_folder": "/docs/", - # Change to an empty value if your GitHub repo doesn't have issues enabled - "github_issues": "enabled", } - -if "discourse" in html_context: - html_context["discourse_prefix"] = html_context["discourse"] + "/t/" - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.ifconfig", - "sphinx.ext.napoleon", - "sphinx.ext.viewcode", - "sphinx_copybutton", - "sphinx_autodoc_typehints", # must be loaded after napoleon - "sphinx-pydantic", - "sphinx_design", + "canonical_sphinx", ] +# endregion + +extensions.extend( + [ + "sphinx.ext.autodoc", + "sphinx.ext.ifconfig", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "sphinx_autodoc_typehints", # must be loaded after napoleon + "sphinxcontrib.details.directive", + ] +) - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. exclude_patterns = [ "_build", "Thumbs.db", ".DS_Store", "env", "sphinx-starter-pack", + # Excluded here because they are either included explicitly in other + # documents (so they generate "duplicate label" errors) or they aren't + # used in this documentation at all (so they generate "unreferenced" + # errors). + "common/craft-parts/explanation/filesets.rst", + "common/craft-parts/explanation/lifecycle.rst", + "common/craft-parts/explanation/overlay_parameters.rst", + "common/craft-parts/explanation/overlays.rst", + "common/craft-parts/explanation/parts.rst", + "common/craft-parts/explanation/how_parts_are_built.rst", + "common/craft-parts/explanation/overlay_step.rst", + "common/craft-parts/how-to/craftctl.rst", + "common/craft-parts/reference/parts_steps.rst", + "common/craft-parts/reference/step_execution_environment.rst", + "common/craft-parts/reference/step_output_directories.rst", + "common/craft-parts/reference/plugins/python_plugin.rst", + # Extra non-craft-parts exclusions can be added after this comment ] -# Links to ignore when checking links linkcheck_ignore = [ "http://0.0.0.0:8080", "https://github.com/canonical/craft-actions#rockcraft-pack", @@ -118,100 +92,11 @@ .. include:: /reuse/links.txt """ -# -- Options for HTML output ------------------------------------------------- +# region Options for extensions - -# 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 = ["_templates"] - - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -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", - "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", - }, -} - - -# 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"] - -# These paths are either relative to html_static_path -# or fully qualified paths (eg. https://...) -html_css_files = [ - "css/custom.css", - "github_issue_links.css", - "custom.css", - "header.css", -] - -html_js_files = ["header-nav.js"] -if "github_issues" in html_context and html_context["github_issues"]: - html_js_files.append("github_issue_links.js") +# Github config +github_username = "canonical" +github_repository = "rockcraft" # Do (not) include module names. add_module_names = True @@ -226,29 +111,7 @@ # Enable support for google-style instance attributes. napoleon_use_ivar = True -extensions.extend(("sphinxcontrib.details.directive",)) - -exclude_patterns.extend( - ( - # Excluded here because they are either included explicitly in other - # documents (so they generate "duplicate label" errors) or they aren't - # used in this documentation at all (so they generate "unreferenced" - # errors). - "common/craft-parts/explanation/filesets.rst", - "common/craft-parts/explanation/lifecycle.rst", - "common/craft-parts/explanation/overlay_parameters.rst", - "common/craft-parts/explanation/overlays.rst", - "common/craft-parts/explanation/parts.rst", - "common/craft-parts/explanation/how_parts_are_built.rst", - "common/craft-parts/explanation/overlay_step.rst", - "common/craft-parts/how-to/craftctl.rst", - "common/craft-parts/reference/parts_steps.rst", - "common/craft-parts/reference/step_execution_environment.rst", - "common/craft-parts/reference/step_output_directories.rst", - "common/craft-parts/reference/plugins/python_plugin.rst", - # Extra non-craft-parts exclusions can be added after this comment - ) -) +# endregion def generate_cli_docs(nil): diff --git a/requirements-doc.txt b/requirements-doc.txt index 4a7e41e2f..861073059 100644 --- a/requirements-doc.txt +++ b/requirements-doc.txt @@ -1,64 +1,80 @@ alabaster==0.7.16 +anyio==4.3.0 Babel==2.14.0 beautifulsoup4==4.12.3 bracex==2.4 +canonical-sphinx==0.1.0 +canonical-sphinx-extensions==0.0.21 certifi==2024.2.2 +cffi==1.16.0 charset-normalizer==3.3.2 +click==8.1.7 colorama==0.4.6 -craft-application==2.4.0 +craft-application==2.6.0 craft-archives==1.1.3 craft-cli==2.5.1 +craft-grammar==1.2.0 craft-parts==1.29.0 craft-providers==1.23.1 Deprecated==1.2.14 distro==1.9.0 -docutils==0.19 +docutils==0.21.2 +exceptiongroup==1.2.1 furo==2024.1.29 +h11==0.14.0 html5lib==1.1 httplib2==0.22.0 -idna==3.6 +idna==3.7 imagesize==1.4.1 -importlib-metadata==7.0.1 +importlib_metadata==7.1.0 Jinja2==3.1.3 -jsonpointer==2.4 launchpadlib==1.11.0 lazr.restfulclient==0.14.6 lazr.uri==1.0.6 -livereload==2.6.3 -lxml==5.1.0 -Markdown==3.5.2 +linkify-it-py==2.0.3 +lxml==5.2.1 +Markdown==3.6 +markdown-it-py==3.0.0 MarkupSafe==2.1.5 +mdit-py-plugins==0.4.0 +mdurl==0.1.2 +myst-parser==3.0.0 oauthlib==3.2.2 overrides==7.7.0 -packaging==23.2 -platformdirs==4.2.0 +packaging==24.0 +pip==22.0.2 +platformdirs==4.2.1 polib==1.2.0 -pydantic==1.10.14 +pycparser==2.22 +pydantic==1.10.15 pydantic-yaml==0.11.2 -Pygments==2.17.2 pygit2==1.14.1 +Pygments==2.17.2 pyparsing==3.1.2 pyspelling==2.10 pyxdg==0.28 PyYAML==6.0.1 -regex==2023.12.25 +regex==2024.4.16 requests==2.31.0 requests-unixsocket==0.3.0 +setuptools==59.6.0 six==1.16.0 +snap-helpers==0.4.2 +sniffio==1.3.1 snowballstemmer==2.2.0 soupsieve==2.5 spdx==2.5.1 spdx-lookup==0.3.3 -Sphinx==6.2.1 -sphinx-autobuild==2021.3.14 -sphinx-autodoc-typehints==1.23.0 +Sphinx==7.3.7 +sphinx-autobuild==2024.4.16 +sphinx-autodoc-typehints==2.1.0 sphinx-basic-ng==1.0.0b2 sphinx-copybutton==0.5.2 -sphinx-jsonschema==1.19.1 -sphinx-lint==0.9.1 -sphinx-pydantic==0.1.1 -sphinx-rtd-theme==2.0.0 sphinx_design==0.5.0 +sphinx-lint==0.9.1 +sphinx-notfound-page==1.0.0 +sphinx-reredirects==0.1.3 +sphinx-tabs==3.4.5 sphinxcontrib-applehelp==1.0.8 sphinxcontrib-details-directive==0.1.0 sphinxcontrib-devhelp==1.0.6 @@ -67,14 +83,20 @@ sphinxcontrib-jquery==4.1 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==1.0.7 sphinxcontrib-serializinghtml==1.1.10 +sphinxext-opengraph==0.9.1 +starlette==0.37.2 tabulate==0.9.0 -tornado==6.4 +tomli==2.0.1 types-Deprecated==1.2.9.20240311 types-PyYAML==6.0.12.20240311 -typing_extensions==4.9.0 +typing_extensions==4.11.0 +uc-micro-py==1.0.3 urllib3==1.26.18 +uvicorn==0.29.0 wadllib==1.3.6 +watchfiles==0.21.0 wcmatch==8.5.1 webencodings==0.5.1 +websockets==12.0 wrapt==1.16.0 -zipp==3.17.0 +zipp==3.18.1 diff --git a/setup.cfg b/setup.cfg index 0ac4598c6..041a9c69b 100644 --- a/setup.cfg +++ b/setup.cfg @@ -45,15 +45,11 @@ rockcraft = py.typed [options.extras_require] doc = - furo - sphinx<7 + canonical-sphinx sphinx-autobuild sphinx-autodoc-typehints - sphinx-copybutton - sphinx_design + sphinxcontrib-details-directive sphinx-lint - sphinx-pydantic - sphinx-rtd-theme pyspelling release = twine