Skip to content

Commit

Permalink
docs: use canonical-sphinx
Browse files Browse the repository at this point in the history 
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"
  • Loading branch information
@tigarmo
tigarmo committed Apr 26, 2024
1 parent 8bdd6b3 commit 116822a
Show file tree
Hide file tree
Showing 7 changed files with 90 additions and 232 deletions.
14 changes: 0 additions & 14 deletions .readthedocs.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,27 +9,13 @@ 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:
configuration: docs/conf.py
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:
Expand Down
8 changes: 1 addition & 7 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Empty file removed docs/_static/.gitempty
View file
Empty file.
3 changes: 0 additions & 3 deletions docs/_static/css/custom.css
View file

This file was deleted.

221 changes: 42 additions & 179 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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",
Expand All @@ -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
Expand All @@ -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):
Expand Down
Loading

0 comments on commit 116822a

Please sign in to comment.