StealthOS/subiquity
StealthOS
/
subiquity
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #1822 from rkratky/sphinx-starter 

Adopt Docs Starter Pack config
This commit is contained in:
Dan Bungert 2023-10-06 07:03:43 -06:00 committed by GitHub
parent e388c263b4 7b1f0c1aed
commit b1e08b5907
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 333 additions and 425 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
doc/.sphinx/requirements.txt
View File

@ -1,6 +1,13 @@
sphinx
sphinx-autobuild
sphinx-design
furo
m2r2
sphinx==5.1.1
sphinx_autobuild
sphinx_copybutton
sphinx_design
sphinx-tabs
sphinx-reredirects
pyspelling
sphinxext-opengraph
lxd-sphinx-extensions
sphinx-copybutton
myst-parser
sphinxcontrib-jquery
sphinx-notfound-page

4
doc/.wokeignore Normal file
View File

@ -0,0 +1,4 @@
# the cheat sheets contain a link to a repository with a block word which we
# cannot avoid for now, ie
# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
doc-cheat-sheet*

37
doc/.wordlist.txt Normal file
View File

@ -0,0 +1,37 @@
addons
API
APIs
balancer
Charmhub
CLI
dropdown
Diátaxis
EBS
EKS
favicon
Grafana
IAM
installable
JSON
Juju
Kubernetes
Kubeflow
Makefile
MyST
namespace
namespaces
NodePort
observability
OLM
Permalink
ReadMe
reST
reStructuredText
RTD
subdirectories
subtree
subfolders
UI
Jira
VM
YAML

2
doc/Makefile
View File

@ -55,7 +55,7 @@ linkcheck:
. $(VENV) ; $(SPHINXBUILD) -c . -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)"
woke:
type woke >/dev/null 2>&1 || { snap install woke; exit 1; }
type woke >/dev/null 2>&1 || { sudo 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

248
doc/_static/css/custom.css vendored
View File

@ -1,248 +0,0 @@
/** Fix the font weight (300 for normal, 400 for slightly bold) **/
/** Should be 100 for all headers, 400 for normal text **/
h1, h2, h3, h4, h5, h6, .sidebar-tree .current-page>.reference, button, input, optgroup, select, textarea, th.head {
font-weight: 200;
}
.toc-title {
font-weight: 400;
}
.sidebar-tree .toctree-l2.has-children>.reference {
font-weight: 300;
}
li.toctree-l3 {
font-weight: 200;
}
div.page, li.scroll-current>.reference, dl.glossary dt, dl.simple dt, dl:not([class]) dt {
font-weight: 300;
line-height: 1.5;
font-size: var(--font-size--normal);
}
/** Side bars (side-bar tree = left, toc-tree = right) **/
div.sidebar-tree {
font-weight: 200;
line-height: 1.5;
font-size: var(--font-size--normal);
}
div.toc-tree {
font-weight: 200;
font-size: var(--font-size--medium);
line-height: 1.5;
}
.sidebar-tree .toctree-l1>.reference, .toc-tree li.scroll-current>.reference {
font-weight: 400;
}
/** List styling **/
ol, ul {
margin-bottom: 1.5rem;
margin-left: 1rem;
margin-top: 0;
padding-left: 1rem;
}
/** 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;
}
/** code blocks and literals **/
code.docutils.literal.notranslate, .highlight pre, pre.literal-block {
font-size: var(--font-size--medium);
}
/** Admonition styling **/
.admonition {
font-size: var(--font-size--medium);
box-shadow: none;
}
/** Styling for links **/
/* unvisited link */
a:link {
color: #06c;
text-decoration: none;
}
/* visited link */
a:visited {
color: #7d42b8;
text-decoration: none;
}
/* mouse over link */
a:hover {
text-decoration: underline;
}
/* selected link */
a:active {
text-decoration: underline;
}
a.sidebar-brand.centered {
text-decoration: none;
}
/** 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);
}
/** Context links at the bottom of the page **/
footer {
font-size: var(--font-size--medium);
}

24
doc/_static/css/github_issue_links.css vendored
View File

@ -1,24 +0,0 @@
.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;
}

7
doc/_static/css/logo.css vendored
View File

@ -1,7 +0,0 @@
.sidebar-brand.centered {
text-align: start;
}
.sidebar-logo {
max-width: 44px;
margin: initial;
}

25
doc/_static/js/github_issue_links.js vendored
View File

@ -1,25 +0,0 @@
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 = (
"https://github.com/canonical/subiquity/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);
};

BIN
doc/_static/ubuntu_logo.png vendored
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 7.6 KiB

220
doc/conf.py
View File

@ -1,138 +1,128 @@
# 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 --------------------------------------------------------------
import datetime
import os
import sys
# 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, use os.path.abspath to make it absolute, like shown:
sys.path.append('./')
from custom_conf import *
#sys.path.insert(0, os.path.abspath('../../'))
#sys.path.insert(0, os.path.abspath('../'))
#sys.path.insert(0, os.path.abspath('./'))
#sys.path.insert(0, os.path.abspath('.'))
# Configuration file for the Sphinx documentation builder.
# You should not do any modifications to this file. Put your custom
# configuration into the custom_conf.py file.
# If you need to change this file, contribute the changes upstream.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
project = 'Ubuntu Install Guide'
copyright = 'Canonical Group Ltd'
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '5.1.1'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
############################################################
### Extensions
############################################################
extensions = [
'sphinx.ext.intersphinx',
'sphinx_copybutton',
'sphinx_design',
'sphinx_tabs.tabs',
'sphinx_reredirects',
'youtube-links',
'related-links',
'custom-rst-roles',
'terminal-output',
'sphinx_copybutton',
'sphinxext.opengraph',
'myst_parser',
'sphinxcontrib.jquery',
'notfound.extension'
]
extensions.extend(custom_extensions)
### Configuration for extensions
# Additional MyST syntax
myst_enable_extensions = [
'substitution',
'deflist'
]
intersphinx_mapping = {
'cloud-init': (
'https://canonical-cloud-init.readthedocs-hosted.com/en/latest',
None
)
# Used for related links
if 'discourse' in html_context:
html_context['discourse_prefix'] = html_context['discourse'] + '/t/'
# The default for notfound_urls_prefix usually works, but not for
# documentation on documentation.ubuntu.com
if slug:
notfound_urls_prefix = '/' + slug + '/en/latest/'
notfound_context = {
'title': 'Page not found',
'body': '<h1>Page not found</h1>\n\n<p>Sorry, but the documentation page that you are looking for was not found.</p>\n<p>Documentation changes over time, and pages are moved around. We try to redirect you to the updated content where possible, but unfortunately, that didn\'t work this time (maybe because the content you were looking for does not exist in this version of the documentation).</p>\n<p>You can try to use the navigation to locate the content you\'re looking for, or search for a similar page.</p>\n',
}
# Add any paths that contain templates here, relative to this directory.
# Default image for OGP (to prevent font errors, see
# https://github.com/canonical/sphinx-docs-starter-pack/pull/54 )
if not 'ogp_image' in locals():
ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg'
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The root toctree document.
root_doc = 'index'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
# version = version.version_string()
# release = version
# 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.
############################################################
### General configuration
############################################################
exclude_patterns = [
'.sphinx/venv/*',
'README.md',
'_build',
'Thumbs.db',
'.DS_Store',
'.sphinx',
]
exclude_patterns.extend(custom_excludes)
# Sphinx-copybutton config options:
# 1) prompt to be stripped from copied code.
# 2) Set to copy all lines (not just prompt lines) to ensure multiline snippets
# can be copied even if they don't contain an EOF line.
copybutton_prompt_text = '$ '
copybutton_only_copy_prompt_lines = False
rst_epilog = '''
.. include:: /reuse/links.txt
'''
if 'custom_rst_epilog' in locals():
rst_epilog = custom_rst_epilog
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes:
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'furo'
html_logo = '_static/ubuntu_logo.png'
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 variable, 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-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',
'sidebar-item-line-height': '1.3rem',
'color-link-underline': 'var(--color-background-primary)',
'color-link-underline--hover': 'var(--color-background-primary)',
},
'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',
},
source_suffix = {
'.rst': 'restructuredtext',
'.md': 'markdown',
}
# 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']
if not 'conf_py_path' in html_context and 'github_folder' in html_context:
html_context['conf_py_path'] = html_context['github_folder']
# If you ever want to use the feedback button, turn on GH issues and then
# uncomment the github_issue_links files
# For ignoring specific links
linkcheck_anchors_ignore_for_url = [
r'https://github\.com/.*'
]
linkcheck_anchors_ignore_for_url.extend(custom_linkcheck_anchors_ignore_for_url)
############################################################
### Styling
############################################################
# 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/_templates']
# Theme configuration
html_theme = 'furo'
html_last_updated_fmt = ''
html_permalinks_icon = ''
############################################################
### Additional files
############################################################
html_static_path = ['.sphinx/_static']
html_css_files = [
'css/logo.css',
# 'css/github_issue_links.css',
'css/custom.css',
]
html_js_files = [
# 'js/github_issue_links.js',
'custom.css',
'header.css',
'github_issue_links.css',
'furo_colors.css'
]
html_css_files.extend(custom_html_css_files)
html_js_files = ['header-nav.js']
if 'github_issues' in html_context and html_context['github_issues'] and not disable_feedback_button:
html_js_files.append('github_issue_links.js')
html_js_files.extend(custom_html_js_files)

172
doc/custom_conf.py Normal file
View File

@ -0,0 +1,172 @@
import datetime
# Custom configuration for the Sphinx documentation builder.
# All configuration specific to your project should be done in this file.
#
# The file is included in the common conf.py configuration file.
# You can modify any of the settings below or add any configuration that
# is not covered by the common conf.py file.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
############################################################
### Project information
############################################################
# Product name
project = 'Ubuntu Install Guide'
author = 'Canonical Group Ltd'
# Uncomment if your product uses release numbers
# release = '1.0'
# The default value uses the current year as the copyright year.
#
# For static works, it is common to provide the year of first publication.
# Another option is to give the first year and the current year
# for documentation that is often changed, e.g. 2022–2023 (note the en-dash).
#
# A way to check a GitHub repo's creation date is to obtain a classic GitHub
# token with 'repo' permissions here: https://github.com/settings/tokens
# Next, use 'curl' and 'jq' to extract the date from the GitHub API's output:
#
# curl -H 'Authorization: token <TOKEN>' \
# -H 'Accept: application/vnd.github.v3.raw' \
# https://api.github.com/repos/canonical/<REPO> | jq '.created_at'
copyright = '%s, %s' % (datetime.date.today().year, author)
## Open Graph configuration - defines what is displayed in the website preview
# The URL of the documentation output
ogp_site_url = 'https://canonical-subiquity.readthedocs-hosted.com/'
# The documentation website name (usually the same as the product name)
ogp_site_name = project
# An image or logo that is used in the preview
ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg'
# Update with the favicon for your product (default is the circle of friends)
html_favicon = '.sphinx/_static/favicon.png'
# (Some settings must be part of the html_context dictionary, while others
# are on root level. Don't move the settings.)
html_context = {
# Change to the link to your product website (without "https://")
'product_page': 'documentation.ubuntu.com',
# 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
# using the :discourse: metadata at the top of a file
# (use an empty value if you don't want to link)
'discourse': 'https://discourse.ubuntu.com',
# Change to the GitHub info for your project
'github_url': 'https://github.com/canonical/subiquity',
# 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': '/doc',
# Change to an empty value if your GitHub repo doesn't have issues enabled.
# This will disable the feedback button and the issue link in the footer.
'github_issues': '',
# Controls the existence of Previous / Next buttons at the bottom of pages
# Valid options: none, prev, next, both
'sequential_nav': "none"
}
# If your project is on documentation.ubuntu.com, specify the project
# slug (for example, "lxd") here.
slug = ""
############################################################
### Redirects
############################################################
# Set up redirects (https://documatt.gitlab.io/sphinx-reredirects/usage.html)
# For example: 'explanation/old-name.html': '../how-to/prettify.html',
redirects = {}
############################################################
### Link checker exceptions
############################################################
# Links to ignore when checking links
linkcheck_ignore = [
'http://127.0.0.1:8000'
]
# Pages on which to ignore anchors
# (This list will be appended to linkcheck_anchors_ignore_for_url)
custom_linkcheck_anchors_ignore_for_url = [
]
############################################################
### Additions to default configuration
############################################################
## The following settings are appended to the default configuration.
## Use them to extend the default functionality.
# Add extensions
custom_extensions = [
'sphinx.ext.intersphinx',
]
# Add files or directories that should be excluded from processing.
custom_excludes = [
'doc-cheat-sheet*',
'.sphinx/venv/*',
'README.md',
]
# Add CSS files (located in .sphinx/_static/)
custom_html_css_files = []
# Add JavaScript files (located in .sphinx/_static/)
custom_html_js_files = []
## The following settings override the default configuration.
# Specify a reST string that is included at the end of each file.
# If commented out, use the default (which pulls the reuse/links.txt
# file into each reST file).
# custom_rst_epilog = ''
# By default, the documentation includes a feedback button at the top.
# You can disable it by setting the following configuration to True.
disable_feedback_button = False
############################################################
### Additional configuration
############################################################
## Add any configuration that is not covered by the common conf.py file.
intersphinx_mapping = {
'cloud-init': (
'https://canonical-cloud-init.readthedocs-hosted.com/en/latest',
None
)
}
# The root toctree document.
root_doc = 'index'
# Sphinx-copybutton config options:
# 1) prompt to be stripped from copied code.
# 2) Set to copy all lines (not just prompt lines) to ensure multiline snippets
# can be copied even if they don't contain an EOF line.
copybutton_prompt_text = '$ '
copybutton_only_copy_prompt_lines = False

2
doc/reuse/links.txt Normal file
View File

@ -0,0 +1,2 @@
.. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/
.. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/