From 92ae9410d2dd78e08e96bb4e390d31995be3c697 Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Thu, 23 May 2024 10:56:31 +0800 Subject: [PATCH 01/14] docs: starter pack --- .github/workflows/automatic-doc-checks.yml | 16 + .wokeignore | 1 + docs/.custom_wordlist.txt | 0 docs/.gitignore | 13 + docs/.readthedocs.yaml | 32 ++ docs/.sphinx/_static/404.svg | 13 + docs/.sphinx/_static/custom.css | 369 ++++++++++++ docs/.sphinx/_static/favicon.png | Bin 0 -> 2258 bytes docs/.sphinx/_static/footer.css | 47 ++ docs/.sphinx/_static/footer.js | 12 + docs/.sphinx/_static/furo_colors.css | 87 +++ docs/.sphinx/_static/github_issue_links.css | 24 + docs/.sphinx/_static/github_issue_links.js | 34 ++ docs/.sphinx/_static/header-nav.js | 10 + docs/.sphinx/_static/header.css | 167 ++++++ docs/.sphinx/_static/tag.png | Bin 0 -> 6781 bytes docs/.sphinx/_templates/404.html | 17 + docs/.sphinx/_templates/base.html | 12 + docs/.sphinx/_templates/footer.html | 131 +++++ docs/.sphinx/_templates/header.html | 36 ++ docs/.sphinx/_templates/page.html | 49 ++ docs/.sphinx/_templates/sidebar/search.html | 7 + docs/.sphinx/build_requirements.py | 127 +++++ docs/.sphinx/pa11y.json | 9 + docs/.sphinx/spellingcheck.yaml | 30 + docs/.wokeignore | 4 + docs/.wordlist.txt | 49 ++ docs/Makefile | 27 + docs/Makefile.sp | 96 ++++ docs/conf.py | 212 +++++++ docs/custom_conf.py | 216 +++++++ docs/doc-cheat-sheet-myst.md | 257 +++++++++ docs/doc-cheat-sheet.rst | 281 ++++++++++ docs/index.rst | 20 + docs/init.sh | 51 ++ docs/make.bat | 35 ++ docs/readme.rst | 592 ++++++++++++++++++++ docs/reuse/links.txt | 4 + 38 files changed, 3087 insertions(+) create mode 100644 .github/workflows/automatic-doc-checks.yml create mode 120000 .wokeignore create mode 100644 docs/.custom_wordlist.txt create mode 100644 docs/.gitignore create mode 100644 docs/.readthedocs.yaml create mode 100644 docs/.sphinx/_static/404.svg create mode 100644 docs/.sphinx/_static/custom.css create mode 100644 docs/.sphinx/_static/favicon.png create mode 100644 docs/.sphinx/_static/footer.css create mode 100644 docs/.sphinx/_static/footer.js create mode 100644 docs/.sphinx/_static/furo_colors.css create mode 100644 docs/.sphinx/_static/github_issue_links.css create mode 100644 docs/.sphinx/_static/github_issue_links.js create mode 100644 docs/.sphinx/_static/header-nav.js create mode 100644 docs/.sphinx/_static/header.css create mode 100644 docs/.sphinx/_static/tag.png create mode 100644 docs/.sphinx/_templates/404.html create mode 100644 docs/.sphinx/_templates/base.html create mode 100644 docs/.sphinx/_templates/footer.html create mode 100644 docs/.sphinx/_templates/header.html create mode 100644 docs/.sphinx/_templates/page.html create mode 100644 docs/.sphinx/_templates/sidebar/search.html create mode 100644 docs/.sphinx/build_requirements.py create mode 100644 docs/.sphinx/pa11y.json create mode 100644 docs/.sphinx/spellingcheck.yaml create mode 100644 docs/.wokeignore create mode 100644 docs/.wordlist.txt create mode 100644 docs/Makefile create mode 100644 docs/Makefile.sp create mode 100644 docs/conf.py create mode 100644 docs/custom_conf.py create mode 100644 docs/doc-cheat-sheet-myst.md create mode 100644 docs/doc-cheat-sheet.rst create mode 100644 docs/index.rst create mode 100755 docs/init.sh create mode 100644 docs/make.bat create mode 100644 docs/readme.rst create mode 100644 docs/reuse/links.txt diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml new file mode 100644 index 000000000..a6eb0ab72 --- /dev/null +++ b/.github/workflows/automatic-doc-checks.yml @@ -0,0 +1,16 @@ +name: Main Documentation Checks + +on: + - push + - pull_request + - workflow_dispatch + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + documentation-checks: + uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main + with: + working-directory: '.' \ No newline at end of file diff --git a/.wokeignore b/.wokeignore new file mode 120000 index 000000000..19f3fe4bd --- /dev/null +++ b/.wokeignore @@ -0,0 +1 @@ +docs/.wokeignore \ No newline at end of file diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt new file mode 100644 index 000000000..e69de29bb diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..374ab3157 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,13 @@ +/*env*/ +.sphinx/venv/ +.sphinx/requirements.txt +.sphinx/warnings.txt +.sphinx/.wordlist.dic +.sphinx/.doctrees/ +.sphinx/node_modules/ +package*.json +_build +.DS_Store +__pycache__ +.idea/ +.vscode/ diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml new file mode 100644 index 000000000..91ca074b4 --- /dev/null +++ b/docs/.readthedocs.yaml @@ -0,0 +1,32 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + jobs: + post_checkout: + - python3 .sphinx/build_requirements.py + apt_packages: + - distro-info + +# Build documentation in the docs/ directory with Sphinx +sphinx: + builder: dirhtml + configuration: conf.py + fail_on_warning: true + +# If using Sphinx, optionally build your docs in additional formats such as PDF +formats: + - pdf + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: .sphinx/requirements.txt diff --git a/docs/.sphinx/_static/404.svg b/docs/.sphinx/_static/404.svg new file mode 100644 index 000000000..b353cd339 --- /dev/null +++ b/docs/.sphinx/_static/404.svg @@ -0,0 +1,13 @@ + + + + + + + + + diff --git a/docs/.sphinx/_static/custom.css b/docs/.sphinx/_static/custom.css new file mode 100644 index 000000000..c81f0981c --- /dev/null +++ b/docs/.sphinx/_static/custom.css @@ -0,0 +1,369 @@ +/** + Ubuntu variable font definitions. + Based on https://github.com/canonical/vanilla-framework/blob/main/scss/_base_fontfaces.scss + + When font files are updated in Vanilla, the links to font files will need to be updated here as well. +*/ + +/* default font set */ +@font-face { + font-family: 'Ubuntu variable'; + font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */ + font-style: normal; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/f1ea362b-Ubuntu%5Bwdth,wght%5D-latin-v0.896a.woff2') format('woff2-variations'); +} + +@font-face { + font-family: 'Ubuntu variable'; + font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */ + font-style: italic; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/90b59210-Ubuntu-Italic%5Bwdth,wght%5D-latin-v0.896a.woff2') format('woff2-variations'); +} + +@font-face { + font-family: 'Ubuntu Mono variable'; + font-style: normal; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/d5fc1819-UbuntuMono%5Bwght%5D-latin-v0.869.woff2') format('woff2-variations'); +} + +/* cyrillic-ext */ +@font-face { + font-family: 'Ubuntu variable'; + font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */ + font-style: normal; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/77cd6650-Ubuntu%5Bwdth,wght%5D-cyrillic-extended-v0.896a.woff2') format('woff2-variations'); + unicode-range: U+0460-052F, U+20B4, U+2DE0-2DFF, U+A640-A69F; +} + +/* cyrillic */ +@font-face { + font-family: 'Ubuntu variable'; + font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */ + font-style: normal; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/2702fce5-Ubuntu%5Bwdth,wght%5D-cyrillic-v0.896a.woff2') format('woff2-variations'); + unicode-range: U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116; +} + +/* greek-ext */ +@font-face { + font-family: 'Ubuntu variable'; + font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */ + font-style: normal; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/5c108b7d-Ubuntu%5Bwdth,wght%5D-greek-extended-v0.896a.woff2') format('woff2-variations'); + unicode-range: U+1F00-1FFF; +} + +/* greek */ +@font-face { + font-family: 'Ubuntu variable'; + font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */ + font-style: normal; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/0a14c405-Ubuntu%5Bwdth,wght%5D-greek-v0.896a.woff2') format('woff2-variations'); + unicode-range: U+0370-03FF; +} + +/* latin-ext */ +@font-face { + font-family: 'Ubuntu variable'; + font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */ + font-style: normal; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/19f68eeb-Ubuntu%5Bwdth,wght%5D-latin-extended-v0.896a.woff2') format('woff2-variations'); + unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF; +} + + +/** Define font-weights as per Vanilla + Based on: https://github.com/canonical/vanilla-framework/blob/main/scss/_base_typography-definitions.scss + + regular text: 400, + bold: 550, + thin: 300, + + h1: bold, + h2: 180; + h3: bold, + h4: 275, + h5: bold, + h6: regular +*/ + +/* default regular text */ +html { + font-weight: 400; +} + +/* heading specific definitions */ +h1, h3, h5 { font-weight: 550; } +h2 { font-weight: 180; } +h4 { font-weight: 275; } + +/* bold */ +.toc-tree li.scroll-current>.reference, +dl.glossary dt, +dl.simple dt, +dl:not([class]) dt { + font-weight: 550; +} + + +/** Table styling **/ + +th.head { + text-transform: uppercase; + font-size: var(--font-size--small); + text-align: initial; +} + +table.align-center th.head { + text-align: center +} + +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; +} + +/* Allow to centre text horizontally in table data cells */ +table.align-center { + text-align: center !important; +} + +/** 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 Sphinx tabs **/ + +[role="tablist"] { + border-bottom: 1px solid var(--color-sidebar-item-background--hover); +} + +.sphinx-tabs-tab[aria-selected="true"], .sd-tab-set>input:checked+label{ + border: 0; + border-bottom: 2px solid var(--color-brand-primary); + font-weight: 400; + font-size: 1rem; + color: var(--color-brand-primary); +} + +body[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"] { + background: var(--color-background-primary); + border-bottom: 2px solid var(--color-brand-primary); +} + +button.sphinx-tabs-tab[aria-selected="false"]:hover, .sd-tab-set>input:not(:checked)+label:hover { + border-bottom: 2px solid var(--color-foreground-border); +} + +button.sphinx-tabs-tab[aria-selected="false"]{ + border-bottom: 2px solid var(--color-background-primary); +} + +body[data-theme="dark"] .sphinx-tabs-tab { + background: var(--color-background-primary); +} + +.sphinx-tabs-tab, .sd-tab-set>label{ + color: var(--color-brand-primary); + font-family: var(--font-stack); + font-weight: 400; + font-size: 1rem; + padding: 1em 1.25em .5em +} + +.sphinx-tabs-panel { + border: 0; + border-bottom: 1px solid var(--color-sidebar-item-background--hover); + background: var(--color-background-primary); + padding: 0.75rem 0 0.75rem 0; +} + +body[data-theme="dark"] .sphinx-tabs-panel { + background: var(--color-background-primary); +} + +/** A tweak for issue #190 **/ + +.highlight .hll { + background-color: var(--color-highlighted-background); +} + + +/** 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); +} + +/** Fix the styling of the version box for readthedocs **/ + +#furo-readthedocs-versions .rst-versions, #furo-readthedocs-versions .rst-current-version, #furo-readthedocs-versions:focus-within .rst-current-version, #furo-readthedocs-versions:hover .rst-current-version { + background: var(--color-sidebar-item-background--hover); +} + +.rst-versions .rst-other-versions dd a { + color: var(--color-link); +} + +#furo-readthedocs-versions:focus-within .rst-current-version .fa-book, #furo-readthedocs-versions:hover .rst-current-version .fa-book, .rst-versions .rst-other-versions { + color: var(--color-sidebar-link-text); +} + +.rst-versions .rst-current-version { + color: var(--color-version-popup); + font-weight: bolder; +} + +/* Code-block copybutton invisible by default + (overriding Furo config to achieve default copybutton setting). */ +.highlight button.copybtn { + opacity: 0; +} + +/* Mimicking the 'Give feedback' button for UX consistency */ +.sidebar-search-container input[type=submit] { + color: #FFFFFF; + border: 2px solid #D6410D; + padding: var(--sidebar-search-input-spacing-vertical) var(--sidebar-search-input-spacing-horizontal); + background: #D6410D; + font-weight: bold; + font-size: var(--font-size--small); + cursor: pointer; +} + +.sidebar-search-container input[type=submit]:hover { + text-decoration: underline; +} + +/* Make inline code the same size as code blocks */ +p code.literal { + border: 0; + font-size: var(--code-font-size); +} + +/* Use the general admonition font size for inline code */ +.admonition p code.literal { + font-size: var(--admonition-font-size); +} + +.highlight .s, .highlight .s1, .highlight .s2 { + color: #3F8100; +} + +.highlight .o { + color: #BB5400; +} diff --git a/docs/.sphinx/_static/favicon.png b/docs/.sphinx/_static/favicon.png new file mode 100644 index 0000000000000000000000000000000000000000..7f175e4617695f752022d2671a0f97fa95bfd895 GIT binary patch literal 2258 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 literal 0 HcmV?d00001 diff --git a/docs/.sphinx/_static/footer.css b/docs/.sphinx/_static/footer.css new file mode 100644 index 000000000..a0a1db454 --- /dev/null +++ b/docs/.sphinx/_static/footer.css @@ -0,0 +1,47 @@ +.display-contributors { + color: var(--color-sidebar-link-text); + cursor: pointer; +} +.all-contributors { + display: none; + z-index: 55; + list-style: none; + position: fixed; + top: 0; + bottom: 0; + left: 0; + right: 0; + width: 200px; + height: 200px; + overflow-y: scroll; + margin: auto; + padding: 0; + background: var(--color-background-primary); + scrollbar-color: var(--color-foreground-border) transparent; + scrollbar-width: thin; +} + +.all-contributors li:hover { + background: var(--color-sidebar-item-background--hover); + width: 100%; +} + +.all-contributors li a{ + color: var(--color-sidebar-link-text); + padding: 1rem; + display: inline-block; +} + +#overlay { + position: fixed; + display: none; + width: 100%; + height: 100%; + top: 0; + left: 0; + right: 0; + bottom: 0; + background-color: rgba(0,0,0,0.5); + z-index: 2; + cursor: pointer; +} diff --git a/docs/.sphinx/_static/footer.js b/docs/.sphinx/_static/footer.js new file mode 100644 index 000000000..9a08b1e99 --- /dev/null +++ b/docs/.sphinx/_static/footer.js @@ -0,0 +1,12 @@ +$(document).ready(function() { + $(document).on("click", function () { + $(".all-contributors").hide(); + $("#overlay").hide(); + }); + + $('.display-contributors').click(function(event) { + $('.all-contributors').toggle(); + $("#overlay").toggle(); + event.stopPropagation(); + }); +}) diff --git a/docs/.sphinx/_static/furo_colors.css b/docs/.sphinx/_static/furo_colors.css new file mode 100644 index 000000000..aa3066694 --- /dev/null +++ b/docs/.sphinx/_static/furo_colors.css @@ -0,0 +1,87 @@ +body { + --color-code-background: #f8f8f8; + --color-code-foreground: black; + --code-font-size: 1rem; + --font-stack: Ubuntu variable, 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-api-background: #E3E3E3; + --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-link); + --color-link-underline--hover: var(--color-link); + --color-version-popup: #772953; +} + +@media not print { + body[data-theme="dark"] { + --color-code-background: #202020; + --color-code-foreground: #d0d0d0; + --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-version-popup: #F29879; + } + @media (prefers-color-scheme: dark) { + body:not([data-theme="light"]) { + --color-api-background: #A4A4A4; + --color-code-background: #202020; + --color-code-foreground: #d0d0d0; + --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: #F9FCFF; + --color-version-popup: #F29879; + } + } +} diff --git a/docs/.sphinx/_static/github_issue_links.css b/docs/.sphinx/_static/github_issue_links.css new file mode 100644 index 000000000..db166ed95 --- /dev/null +++ b/docs/.sphinx/_static/github_issue_links.css @@ -0,0 +1,24 @@ +.github-issue-link-container { + padding-right: 0.5rem; +} +.github-issue-link { + font-size: var(--font-size--small); + font-weight: bold; + background-color: #D6410D; + 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; +} diff --git a/docs/.sphinx/_static/github_issue_links.js b/docs/.sphinx/_static/github_issue_links.js new file mode 100644 index 000000000..f0706038b --- /dev/null +++ b/docs/.sphinx/_static/github_issue_links.js @@ -0,0 +1,34 @@ +// if we already have an onload function, save that one +var prev_handler = window.onload; + +window.onload = function() { + // call the previous onload function + if (prev_handler) { + prev_handler(); + } + + const link = document.createElement("a"); + link.classList.add("muted-link"); + link.classList.add("github-issue-link"); + link.text = "Give feedback"; + link.href = ( + github_url + + "/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); +}; diff --git a/docs/.sphinx/_static/header-nav.js b/docs/.sphinx/_static/header-nav.js new file mode 100644 index 000000000..3608576e0 --- /dev/null +++ b/docs/.sphinx/_static/header-nav.js @@ -0,0 +1,10 @@ +$(document).ready(function() { + $(document).on("click", function () { + $(".more-links-dropdown").hide(); + }); + + $('.nav-more-links').click(function(event) { + $('.more-links-dropdown').toggle(); + event.stopPropagation(); + }); +}) diff --git a/docs/.sphinx/_static/header.css b/docs/.sphinx/_static/header.css new file mode 100644 index 000000000..0b9440903 --- /dev/null +++ b/docs/.sphinx/_static/header.css @@ -0,0 +1,167 @@ +.p-navigation { + border-bottom: 1px solid var(--color-sidebar-background-border); +} + +.p-navigation__nav { + background: #333333; + display: flex; +} + +.p-logo { + display: flex !important; + padding-top: 0 !important; + text-decoration: none; +} + +.p-logo-image { + height: 44px; + padding-right: 10px; +} + +.p-logo-text { + margin-top: 18px; + color: white; + text-decoration: none; +} + +ul.p-navigation__links { + display: flex; + list-style: none; + margin-left: 0; + margin-top: auto; + margin-bottom: auto; + max-width: 800px; + width: 100%; +} + +ul.p-navigation__links li { + margin: 0 auto; + text-align: center; + width: 100%; +} + +ul.p-navigation__links li a { + background-color: rgba(0, 0, 0, 0); + border: none; + border-radius: 0; + color: var(--color-sidebar-link-text); + display: block; + font-weight: 400; + line-height: 1.5rem; + margin: 0; + overflow: hidden; + padding: 1rem 0; + position: relative; + text-align: left; + text-overflow: ellipsis; + transition-duration: .1s; + transition-property: background-color, color, opacity; + transition-timing-function: cubic-bezier(0.215, 0.61, 0.355, 1); + white-space: nowrap; + width: 100%; +} + +ul.p-navigation__links .p-navigation__link { + color: #ffffff; + font-weight: 300; + text-align: center; + text-decoration: none; +} + +ul.p-navigation__links .p-navigation__link:hover { + background-color: #2b2b2b; +} + +ul.p-navigation__links .p-dropdown__link:hover { + background-color: var(--color-sidebar-item-background--hover); +} + +ul.p-navigation__links .p-navigation__sub-link { + background: var(--color-background-primary); + padding: .5rem 0 .5rem .5rem; + font-weight: 300; +} + +ul.p-navigation__links .more-links-dropdown li a { + border-left: 1px solid var(--color-sidebar-background-border); + border-right: 1px solid var(--color-sidebar-background-border); +} + +ul.p-navigation__links .more-links-dropdown li:first-child a { + border-top: 1px solid var(--color-sidebar-background-border); +} + +ul.p-navigation__links .more-links-dropdown li:last-child a { + border-bottom: 1px solid var(--color-sidebar-background-border); +} + +ul.p-navigation__links .p-navigation__logo { + padding: 0.5rem; +} + +ul.p-navigation__links .p-navigation__logo img { + width: 40px; +} + +ul.more-links-dropdown { + display: none; + overflow-x: visible; + height: 0; + z-index: 55; + padding: 0; + position: relative; + list-style: none; + margin-bottom: 0; + margin-top: 0; +} + +.nav-more-links::after { + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16'%3E%3Cpath fill='%23111' d='M8.187 11.748l6.187-6.187-1.06-1.061-5.127 5.127L3.061 4.5 2 5.561z'/%3E%3C/svg%3E"); + background-position: center; + background-repeat: no-repeat; + background-size: contain; + content: ""; + display: block; + filter: invert(100%); + height: 1rem; + pointer-events: none; + position: absolute; + right: 1rem; + text-indent: calc(100% + 10rem); + top: calc(1rem + 0.25rem); + width: 1rem; +} + +.nav-ubuntu-com { + display: none; +} + +@media only screen and (min-width: 480px) { + ul.p-navigation__links li { + width: 100%; + } + + .nav-ubuntu-com { + display: inherit; + } +} + +@media only screen and (max-width: 800px) { + .nav-more-links { + margin-left: auto !important; + padding-right: 2rem !important; + width: 8rem !important; + } +} + +@media only screen and (min-width: 800px) { + ul.p-navigation__links li { + width: 100% !important; + } +} + +@media only screen and (min-width: 1310px) { + ul.p-navigation__links { + margin-left: calc(50% - 41em); + } +} diff --git a/docs/.sphinx/_static/tag.png b/docs/.sphinx/_static/tag.png new file mode 100644 index 0000000000000000000000000000000000000000..f6f6e5aa4bc55fb934c973726b10a0efc92445a8 GIT binary patch literal 6781 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 literal 0 HcmV?d00001 diff --git a/docs/.sphinx/_templates/404.html b/docs/.sphinx/_templates/404.html new file mode 100644 index 000000000..4cb2d50d3 --- /dev/null +++ b/docs/.sphinx/_templates/404.html @@ -0,0 +1,17 @@ +{% extends "page.html" %} + +{% block content -%} +
+

Page not found

+
+
+
+ {{ body }} +
+
+ Penguin with a question mark +
+
+
+
+{%- endblock content %} diff --git a/docs/.sphinx/_templates/base.html b/docs/.sphinx/_templates/base.html new file mode 100644 index 000000000..33081547c --- /dev/null +++ b/docs/.sphinx/_templates/base.html @@ -0,0 +1,12 @@ +{% extends "furo/base.html" %} + +{% block theme_scripts %} + +{% endblock theme_scripts %} + +{# ru-fu: don't include the color variables from the conf.py file, but use a + separate CSS file to save space #} +{% block theme_styles %} +{% endblock theme_styles %} diff --git a/docs/.sphinx/_templates/footer.html b/docs/.sphinx/_templates/footer.html new file mode 100644 index 000000000..6839f0154 --- /dev/null +++ b/docs/.sphinx/_templates/footer.html @@ -0,0 +1,131 @@ +{# ru-fu: copied from Furo, with modifications as stated below. Modifications are marked 'mod:'. #} + +
+ {# mod: Per-page navigation #} + {% if meta %} + {% if 'sequential_nav' in meta %} + {% set sequential_nav = meta.sequential_nav %} + {% endif %} + {% endif %} + {# mod: Conditional wrappers to control page navigation buttons #} + {% if sequential_nav != "none" -%} + {% if next and (sequential_nav == "next" or sequential_nav == "both") -%} + +
+
+ {{ _("Next") }} +
+
{{ next.title }}
+
+ + + {%- endif %} + {% if prev and (sequential_nav == "prev" or sequential_nav == "both") -%} + + +
+
+ {{ _("Previous") }} +
+ {% if prev.link == pathto(root_doc) %} +
{{ _("Home") }}
+ {% else %} +
{{ prev.title }}
+ {% endif %} +
+ + {%- endif %} + {%- endif %} +
+
+
+ {%- if show_copyright %} +
+ {%- if hasdoc('copyright') %} + {% trans path=pathto('copyright'), copyright=copyright|e -%} + Copyright © {{ copyright }} + {%- endtrans %} + {%- else %} + {% trans copyright=copyright|e -%} + Copyright © {{ copyright }} + {%- endtrans %} + {%- 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 %} +
+ Show source +
+ {%- endif %} +
+
+ {% if github_url and github_folder and pagename and page_source_suffix and display_contributors %} + {% set contributors = get_contribs(github_url, github_folder, pagename, page_source_suffix, display_contributors_since) %} + {% if contributors %} + {% if contributors | length > 1 %} + Thanks to the {{ contributors |length }} contributors! + {% else %} + Thanks to our contributor! + {% endif %} +
+ + {% endif %} + {% endif %} +
+
+ + {# mod: replaced RTD icons with our links #} + + {% if discourse %} +
+ Ask a question on Discourse +
+ {% endif %} + + {% if mattermost %} +
+ Ask a question on Mattermost +
+ {% endif %} + + {% if matrix %} +
+ Ask a question on Matrix +
+ {% endif %} + + {% if github_url and github_version and github_folder %} + + {% if github_issues %} +
+ Open a GitHub issue for this page +
+ {% endif %} + +
+ Edit this page on GitHub +
+ {% endif %} + + +
+
+ diff --git a/docs/.sphinx/_templates/header.html b/docs/.sphinx/_templates/header.html new file mode 100644 index 000000000..1a128b6f8 --- /dev/null +++ b/docs/.sphinx/_templates/header.html @@ -0,0 +1,36 @@ + diff --git a/docs/.sphinx/_templates/page.html b/docs/.sphinx/_templates/page.html new file mode 100644 index 000000000..bda306109 --- /dev/null +++ b/docs/.sphinx/_templates/page.html @@ -0,0 +1,49 @@ +{% extends "furo/page.html" %} + +{% block footer %} + {% include "footer.html" %} +{% endblock footer %} + +{% block body -%} + {% include "header.html" %} + {{ super() }} +{%- endblock body %} + +{% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %} + {% set furo_hide_toc_orig = furo_hide_toc %} + {% set furo_hide_toc=false %} +{% endif %} + +{% block right_sidebar %} +
+ {% if not furo_hide_toc_orig %} +
+ + {{ _("Contents") }} + +
+
+
+ {{ toc }} +
+
+ {% endif %} + {% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %} +
+ + Related links + +
+
+
+ {% if meta.discourse and discourse_prefix %} + {{ discourse_links(meta.discourse) }} + {% endif %} + {% if meta.relatedlinks %} + {{ related_links(meta.relatedlinks) }} + {% endif %} +
+
+ {% endif %} +
+{% endblock right_sidebar %} diff --git a/docs/.sphinx/_templates/sidebar/search.html b/docs/.sphinx/_templates/sidebar/search.html new file mode 100644 index 000000000..644a5ef6a --- /dev/null +++ b/docs/.sphinx/_templates/sidebar/search.html @@ -0,0 +1,7 @@ + + diff --git a/docs/.sphinx/build_requirements.py b/docs/.sphinx/build_requirements.py new file mode 100644 index 000000000..df6f149b4 --- /dev/null +++ b/docs/.sphinx/build_requirements.py @@ -0,0 +1,127 @@ +import sys + +sys.path.append('./') +from custom_conf import * + +# The file contains helper functions and the mechanism to build the +# .sphinx/requirements.txt file that is needed to set up the virtual +# environment. + +# You should not do any modifications to this file. Put your custom +# requirements into the custom_required_modules array in the custom_conf.py +# file. If you need to change this file, contribute the changes upstream. + +legacyCanonicalSphinxExtensionNames = [ + "youtube-links", + "related-links", + "custom-rst-roles", + "terminal-output" + ] + +def IsAnyCanonicalSphinxExtensionUsed(): + for extension in custom_extensions: + if (extension.startswith("canonical.") or + extension in legacyCanonicalSphinxExtensionNames): + return True + + return False + +def IsNotFoundExtensionUsed(): + return "notfound.extension" in custom_extensions + +def IsSphinxTabsUsed(): + for extension in custom_extensions: + if extension.startswith("sphinx_tabs."): + return True + + return False + +def AreRedirectsDefined(): + return ("sphinx_reredirects" in custom_extensions) or ( + ("redirects" in globals()) and \ + (redirects is not None) and \ + (len(redirects) > 0)) + +def IsOpenGraphConfigured(): + if "sphinxext.opengraph" in custom_extensions: + return True + + for global_variable_name in list(globals()): + if global_variable_name.startswith("ogp_"): + return True + + return False + +def IsMyStParserUsed(): + return ("myst_parser" in custom_extensions) or \ + ("custom_myst_extensions" in globals()) + +def DeduplicateExtensions(extensionNames: [str]): + extensionNames = dict.fromkeys(extensionNames) + resultList = [] + encounteredCanonicalExtensions = [] + + for extensionName in extensionNames: + if extensionName in legacyCanonicalSphinxExtensionNames: + extensionName = "canonical." + extensionName + + if extensionName.startswith("canonical."): + if extensionName not in encounteredCanonicalExtensions: + encounteredCanonicalExtensions.append(extensionName) + resultList.append(extensionName) + else: + resultList.append(extensionName) + + return resultList + +if __name__ == "__main__": + requirements = [ + "furo", + "pyspelling", + "sphinx", + "sphinx-autobuild", + "sphinx-copybutton", + "sphinx-design", + "sphinxcontrib-jquery", + "watchfiles", + "GitPython" + + ] + + requirements.extend(custom_required_modules) + + if IsAnyCanonicalSphinxExtensionUsed(): + requirements.append("canonical-sphinx-extensions") + + if IsNotFoundExtensionUsed(): + requirements.append("sphinx-notfound-page") + + if IsSphinxTabsUsed(): + requirements.append("sphinx-tabs") + + if AreRedirectsDefined(): + requirements.append("sphinx-reredirects") + + if IsOpenGraphConfigured(): + requirements.append("sphinxext-opengraph") + + if IsMyStParserUsed(): + requirements.append("myst-parser") + requirements.append("linkify-it-py") + + # removes duplicate entries + requirements = list(dict.fromkeys(requirements)) + requirements.sort() + + with open(".sphinx/requirements.txt", 'w') as requirements_file: + requirements_file.write( + "# DO NOT MODIFY THIS FILE DIRECTLY!\n" + "#\n" + "# This file is generated automatically.\n" + "# Add custom requirements to the custom_required_modules\n" + "# array in the custom_conf.py file and run:\n" + "# make clean && make install\n") + + for requirement in requirements: + requirements_file.write(requirement) + requirements_file.write('\n') diff --git a/docs/.sphinx/pa11y.json b/docs/.sphinx/pa11y.json new file mode 100644 index 000000000..8df0cb9cb --- /dev/null +++ b/docs/.sphinx/pa11y.json @@ -0,0 +1,9 @@ +{ + "chromeLaunchConfig": { + "args": [ + "--no-sandbox" + ] + }, + "reporter": "cli", + "standard": "WCAG2AA" +} \ No newline at end of file diff --git a/docs/.sphinx/spellingcheck.yaml b/docs/.sphinx/spellingcheck.yaml new file mode 100644 index 000000000..467676ddd --- /dev/null +++ b/docs/.sphinx/spellingcheck.yaml @@ -0,0 +1,30 @@ +matrix: +- name: rST files + aspell: + lang: en + d: en_GB + dictionary: + wordlists: + - .wordlist.txt + - .custom_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 + - strong.command + - div.visually-hidden + - img + - a.p-navigation__link + - a.contributor diff --git a/docs/.wokeignore b/docs/.wokeignore new file mode 100644 index 000000000..c64a60376 --- /dev/null +++ b/docs/.wokeignore @@ -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* diff --git a/docs/.wordlist.txt b/docs/.wordlist.txt new file mode 100644 index 000000000..cea5bdb46 --- /dev/null +++ b/docs/.wordlist.txt @@ -0,0 +1,49 @@ +addons +API +APIs +balancer +Charmhub +CLI +Diátaxis +dropdown +EBS +EKS +enablement +favicon +Furo +Git +GitHub +Grafana +IAM +installable +JSON +Juju +Kubeflow +Kubernetes +Launchpad +LTS +Makefile +Matrix +Mattermost +MyST +namespace +namespaces +NodePort +observability +OEM +OLM +Permalink +pre +Quickstart +ReadMe +reST +reStructuredText +RTD +subdirectories +subfolders +subtree +Ubuntu +UI +UUID +VM +YAML diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..5138e061e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,27 @@ +# This Makefile stub allows you to customize starter pack (SP) targets. +# Consider this file as a bridge between your project +# and the starter pack's predefined targets that reside in Makefile.sp. +# +# You can add your own, non-SP targets here or override SP targets +# to fit your project's needs. For example, you can define and use targets +# named "install" or "run", but continue to use SP targets like "sp-install" +# or "sp-run" when working on the documentation. + +# Put it first so that "make" without argument is like "make help". +help: + @echo "\n" \ + "------------------------------------------------------------- \n" \ + "* watch, build and serve the documentation: make run \n" \ + "* only build: make html \n" \ + "* only serve: make serve \n" \ + "* clean built doc files: make clean-doc \n" \ + "* clean full environment: make clean \n" \ + "* check links: make linkcheck \n" \ + "* check spelling: make spelling \n" \ + "* check inclusive language: make woke \n" \ + "* check accessibility: make pa11y \n" \ + "* other possible targets: make \n" \ + "------------------------------------------------------------- \n" + +%: + $(MAKE) -f Makefile.sp sp-$@ diff --git a/docs/Makefile.sp b/docs/Makefile.sp new file mode 100644 index 000000000..b85f6b43f --- /dev/null +++ b/docs/Makefile.sp @@ -0,0 +1,96 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXDIR = .sphinx +SPHINXOPTS ?= -c . -d $(SPHINXDIR)/.doctrees +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build +VENVDIR = $(SPHINXDIR)/venv +PA11Y = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json +VENV = $(VENVDIR)/bin/activate + +.PHONY: sp-full-help sp-woke-install sp-pa11y-install sp-install sp-run sp-html \ + sp-epub sp-serve sp-clean sp-clean-doc sp-spelling sp-linkcheck sp-woke \ + sp-pa11y Makefile.sp + +sp-full-help: $(VENVDIR) + @. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m" + @echo "Run 'make help' to see supported targets." + +# Shouldn't assume that venv is available on Ubuntu by default; discussion here: +# https://bugs.launchpad.net/ubuntu/+source/python3.4/+bug/1290847 +$(SPHINXDIR)/requirements.txt: + python3 $(SPHINXDIR)/build_requirements.py + python3 -c "import venv" || sudo apt install python3-venv + +# If requirements are updated, venv should be rebuilt and timestamped. +$(VENVDIR): $(SPHINXDIR)/requirements.txt + @echo "... setting up virtualenv" + python3 -m venv $(VENVDIR) + . $(VENV); pip install --require-virtualenv \ + --upgrade -r $(SPHINXDIR)/requirements.txt \ + --log $(VENVDIR)/pip_install.log + @test ! -f $(VENVDIR)/pip_list.txt || \ + mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak + @. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt + @touch $(VENVDIR) + +sp-woke-install: + @type woke >/dev/null 2>&1 || \ + { echo "Installing \"woke\" snap... \n"; sudo snap install woke; } + +sp-pa11y-install: + @type $(PA11Y) >/dev/null 2>&1 || { \ + echo "Installing \"pa11y\" from npm... \n"; \ + mkdir -p $(SPHINXDIR)/node_modules/ ; \ + npm install --prefix $(SPHINXDIR) pa11y; \ + } + +sp-install: $(VENVDIR) + sudo apt-get update + sudo apt-get install --assume-yes distro-info + +sp-run: sp-install + . $(VENV); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) + +# Doesn't depend on $(BUILDDIR) to rebuild properly at every run. +sp-html: sp-install + . $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) + +sp-epub: sp-install + . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) + +sp-serve: sp-html + cd "$(BUILDDIR)"; python3 -m http.server 8000 + +sp-clean: sp-clean-doc + @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)" + rm -rf $(VENVDIR) + rm -f $(SPHINXDIR)/requirements.txt + rm -rf $(SPHINXDIR)/node_modules/ + +sp-clean-doc: + git clean -fx "$(BUILDDIR)" + rm -rf $(SPHINXDIR)/.doctrees + +sp-spelling: sp-html + . $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc) + +sp-linkcheck: sp-install + . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) + +sp-woke: sp-woke-install + woke *.rst **/*.rst --exit-1-on-failure \ + -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml + +sp-pa11y: sp-pa11y-install sp-html + find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y) + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile.sp + . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..16f8522f8 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,212 @@ +import sys +import os +import requests +from urllib.parse import urlparse +from git import Repo +import subprocess +import time + +sys.path.append('./') +from custom_conf import * +sys.path.append('.sphinx/') +from build_requirements import * + +# 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 + +############################################################ +### Extensions +############################################################ + +extensions = [ + 'sphinx_design', + 'sphinx_copybutton', + 'sphinxcontrib.jquery', +] + +# Only add redirects extension if any redirects are specified. +if AreRedirectsDefined(): + extensions.append('sphinx_reredirects') + +# Only add myst extensions if any configuration is present. +if IsMyStParserUsed(): + extensions.append('myst_parser') + + # Additional MyST syntax + myst_enable_extensions = [ + 'substitution', + 'deflist', + 'linkify' + ] + myst_enable_extensions.extend(custom_myst_extensions) + +# Only add Open Graph extension if any configuration is present. +if IsOpenGraphConfigured(): + extensions.append('sphinxext.opengraph') + +extensions.extend(custom_extensions) +extensions = DeduplicateExtensions(extensions) + +### Configuration for extensions + +# Used for related links +if not 'discourse_prefix' in html_context and 'discourse' in html_context: + html_context['discourse_prefix'] = html_context['discourse'] + '/t/' + +# The URL prefix for the notfound extension depends on whether the documentation uses versions. +# For documentation on documentation.ubuntu.com, we also must add the slug. +url_version = '' +url_lang = '' + +# Determine if the URL uses versions and language +if 'READTHEDOCS_CANONICAL_URL' in os.environ and os.environ['READTHEDOCS_CANONICAL_URL']: + url_parts = os.environ['READTHEDOCS_CANONICAL_URL'].split('/') + + if len(url_parts) >= 2 and 'READTHEDOCS_VERSION' in os.environ and os.environ['READTHEDOCS_VERSION'] == url_parts[-2]: + url_version = url_parts[-2] + '/' + + if len(url_parts) >= 3 and 'READTHEDOCS_LANGUAGE' in os.environ and os.environ['READTHEDOCS_LANGUAGE'] == url_parts[-3]: + url_lang = url_parts[-3] + '/' + +# Set notfound_urls_prefix to the slug (if defined) and the version/language affix +if slug: + notfound_urls_prefix = '/' + slug + '/' + url_lang + url_version +elif len(url_lang + url_version) > 0: + notfound_urls_prefix = '/' + url_lang + url_version +else: + notfound_urls_prefix = '' + +notfound_context = { + 'title': 'Page not found', + 'body': '

Sorry, but the documentation page that you are looking for was not found.

\n\n

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).

\n

You can try to use the navigation to locate the content you\'re looking for, or search for a similar page.

\n', +} + +# 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' + +############################################################ +### General configuration +############################################################ + +exclude_patterns = [ + '_build', + 'Thumbs.db', + '.DS_Store', + '.sphinx', +] +exclude_patterns.extend(custom_excludes) + +rst_epilog = ''' +.. include:: /reuse/links.txt +''' +if 'custom_rst_epilog' in locals(): + rst_epilog = custom_rst_epilog + +if 'custom_manpages_url' in locals(): + manpages_url = custom_manpages_url +else: + manpages_distribution = subprocess.check_output("distro-info --stable", + text=True, shell=True).strip() + manpages_url = ("https://manpages.ubuntu.com/manpages/" + f"{manpages_distribution}/en/" + "man{section}/{page}.{section}.html") + +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} + +if not 'conf_py_path' in html_context and 'github_folder' in html_context: + html_context['conf_py_path'] = html_context['github_folder'] + +# 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) + +# Tags cannot be added directly in custom_conf.py, so add them here +for tag in custom_tags: + tags.add(tag) + +# html_context['get_contribs'] is a function and cannot be +# cached (see https://github.com/sphinx-doc/sphinx/issues/12300) +suppress_warnings = ["config.cache"] + +############################################################ +### 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'] + notfound_template = '404.html' + +# Theme configuration +html_theme = 'furo' +html_last_updated_fmt = '' +html_permalinks_icon = '¶' + +if html_title == '': + html_theme_options = { + 'sidebar_hide_name': True + } + +############################################################ +### Additional files +############################################################ + +html_static_path = ['.sphinx/_static'] + +html_css_files = [ + 'custom.css', + 'header.css', + 'github_issue_links.css', + 'furo_colors.css', + 'footer.css' +] +html_css_files.extend(custom_html_css_files) + +html_js_files = ['header-nav.js', 'footer.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) + +############################################################# +# Display the contributors + +def get_contributors_for_file(github_url, github_folder, pagename, page_source_suffix, display_contributors_since=None): + filename = f"{pagename}{page_source_suffix}" + paths=html_context['github_folder'][1:] + filename + repo = Repo(".") + since = display_contributors_since if display_contributors_since and display_contributors_since.strip() else None + + commits = repo.iter_commits(paths=paths, since=since) + + contributors_dict = {} + for commit in commits: + contributor = commit.author.name + if contributor not in contributors_dict or commit.committed_date > contributors_dict[contributor]['date']: + contributors_dict[contributor] = { + 'date': commit.committed_date, + 'sha': commit.hexsha + } + # The github_page contains the link to the contributor's latest commit. + contributors_list = [{'name': name, 'github_page': f"{github_url}/commit/{data['sha']}"} for name, data in contributors_dict.items()] + sorted_contributors_list = sorted(contributors_list, key=lambda x: x['name']) + return sorted_contributors_list + +html_context['get_contribs'] = get_contributors_for_file +############################################################# diff --git a/docs/custom_conf.py b/docs/custom_conf.py new file mode 100644 index 000000000..f393ea093 --- /dev/null +++ b/docs/custom_conf.py @@ -0,0 +1,216 @@ +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 +# +# If you're not familiar with Sphinx and don't want to use advanced +# features, it is sufficient to update the settings in the "Project +# information" section. + +############################################################ +### Project information +############################################################ + +# Product name +project = 'Documentation starter pack' +author = 'Canonical Group Ltd' + +# The title you want to display for the documentation in the sidebar. +# You might want to include a version number here. +# To not display any title, set this option to an empty string. +html_title = project + ' documentation' + +# 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 ' \ +# -H 'Accept: application/vnd.github.v3.raw' \ +# https://api.github.com/repos/canonical/ | jq '.created_at' + +copyright = '%s, %s' % (datetime.date.today().year, author) + +## Open Graph configuration - defines what is displayed as a link preview +## when linking to the documentation from another website (see https://ogp.me/) +# The URL where the documentation will be hosted (leave empty if you +# don't know yet) +# NOTE: If no ogp_* variable is defined (e.g. if you remove this section) the +# sphinxext.opengraph extension will be disabled. +ogp_site_url = 'https://canonical-starter-pack.readthedocs-hosted.com/' +# The documentation website name (usually the same as the product name) +ogp_site_name = project +# The URL of 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 local path to 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 the website of your product (without "https://") + # For example: "ubuntu.com/lxd" or "microcloud.is" + # If there is no product website, edit the header template to remove the + # link (see the readme for instructions). + 'product_page': 'documentation.ubuntu.com', + + # Add your product tag (the orange part of your logo, will be used in the + # header) 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 Mattermost channel you want to link to + # (use an empty value if you don't want to link) + 'mattermost': 'https://chat.canonical.com/canonical/channels/documentation', + + # Change to the Matrix channel you want to link to + # (use an empty value if you don't want to link) + 'matrix': 'https://matrix.to/#/#documentation:ubuntu.com', + + # Change to the GitHub URL for your project + # This is used, for example, to link to the source files and allow creating GitHub issues directly from the documentation. + 'github_url': 'https://github.com/canonical/sphinx-docs-starter-pack', + + # 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': '/', + + # 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': 'enabled', + + # Controls the existence of Previous / Next buttons at the bottom of pages + # Valid options: none, prev, next, both + 'sequential_nav': "none", + + # Controls if to display the contributors of a file or not + "display_contributors": True, + + # Controls time frame for showing the contributors + "display_contributors_since": "" +} + +# 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', +# You can also configure redirects in the Read the Docs project dashboard +# (see https://docs.readthedocs.io/en/stable/guides/redirects.html). +# NOTE: If this variable is not defined, set to None, or the dictionary is empty, +# the sphinx_reredirects extension will be disabled. +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 +############################################################ + +# Uncomment to overwrite Ubuntu manpages URL template for :manpage: directives: +# custom_manpages_url = "https://customurl/man{section}/{page}.{section}.html" + +## The following settings are appended to the default configuration. +## Use them to extend the default functionality. +# NOTE: Remove this variable to disable the MyST parser extensions. +custom_myst_extensions = [] + +# Add custom Sphinx extensions as needed. +# This array contains recommended extensions that should be used. +# NOTE: The following extensions are handled automatically and do +# not need to be added here: myst_parser, sphinx_copybutton, sphinx_design, +# sphinx_reredirects, sphinxcontrib.jquery, sphinxext.opengraph +custom_extensions = [ + 'sphinx_tabs.tabs', + 'canonical.youtube-links', + 'canonical.related-links', + 'canonical.custom-rst-roles', + 'canonical.terminal-output', + 'notfound.extension' + ] + +# Add custom required Python modules that must be added to the +# .sphinx/requirements.txt file. +# NOTE: The following modules are handled automatically and do not need to be +# added here: canonical-sphinx-extensions, furo, linkify-it-py, myst-parser, +# pyspelling, sphinx, sphinx-autobuild, sphinx-copybutton, sphinx-design, +# sphinx-notfound-page, sphinx-reredirects, sphinx-tabs, sphinxcontrib-jquery, +# sphinxext-opengraph +custom_required_modules = [] + +# Add files or directories that should be excluded from processing. +custom_excludes = [ + 'doc-cheat-sheet*', + ] + +# 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 + +# Add tags that you want to use for conditional inclusion of text +# (https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#tags) +custom_tags = [] + +############################################################ +### Additional configuration +############################################################ + +## Add any configuration that is not covered by the common conf.py file. + +# Define a :center: role that can be used to center the content of table cells. +rst_prolog = ''' +.. role:: center + :class: align-center +''' diff --git a/docs/doc-cheat-sheet-myst.md b/docs/doc-cheat-sheet-myst.md new file mode 100644 index 000000000..11731d804 --- /dev/null +++ b/docs/doc-cheat-sheet-myst.md @@ -0,0 +1,257 @@ +--- +orphan: true +myst: + substitutions: + reuse_key: "This is **included** text." + advanced_reuse_key: "This is a substitution that includes a code block: + ``` + code block + ```" +--- + +(cheat-sheet-myst)= +# Markdown/MyST cheat sheet + +This file contains the syntax for commonly used Markdown and MyST markup. +Open it in your text editor to quickly copy and paste the markup you need. + +Also see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/index.html) for detailed information, and the [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) for general style conventions. + +## H2 heading + +### H3 heading + +#### H4 heading + +##### H5 heading + +## Inline formatting + +- {guilabel}`UI element` +- `code` +- {command}`command` +- {kbd}`Key` +- *Italic* +- **Bold** + +## Code blocks + +Start a code block: + + code: + - example: true + +``` +# Demonstrate a code block +code: + - example: true +``` + +```yaml +# Demonstrate a code block +code: + - example: true +``` + +(a_section_target_myst)= +## Links + +- [Canonical website](https://canonical.com/) +- https://canonical.com/ +- {ref}`a_section_target_myst` +- {ref}`Link text ` +- {doc}`index` +- {doc}`Link text ` + + +## Navigation + +Use the following syntax:: + + ```{toctree} + :hidden: + + sub-page1 + sub-page2 + ``` + +## Lists + +1. Step 1 + - Item 1 + * Sub-item + - Item 2 + 1. Sub-step 1 + 1. Sub-step 2 +1. Step 2 + 1. Sub-step 1 + - Item + 1. Sub-step 2 + +Term 1 +: Definition + +Term 2 +: Definition + +## Tables + +## Markdown tables + +| Header 1 | Header 2 | +|------------------------------------|----------| +| Cell 1
Second paragraph | Cell 2 | +| Cell 3 | Cell 4 | + +Centred: + +| Header 1 | Header 2 | +|:----------------------------------:|:--------:| +| Cell 1
Second paragraph | Cell 2 | +| Cell 3 | Cell 4 | + +## List tables + +```{list-table} + :header-rows: 1 + +* - Header 1 + - Header 2 +* - Cell 1 + + Second paragraph + - Cell 2 +* - Cell 3 + - Cell 4 +``` + +Centred: + +```{list-table} + :header-rows: 1 + :align: center + +* - Header 1 + - Header 2 +* - Cell 1 + + Second paragraph + - Cell 2 +* - Cell 3 + - Cell 4 +``` + +## Notes + +```{note} +A note. +``` + +```{tip} +A tip. +``` + +```{important} +Important information +``` + +```{caution} +This might damage your hardware! +``` + +## Images + +![Alt text](https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png) + +```{figure} https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png + :width: 100px + :alt: Alt text + + Figure caption +``` + +## Reuse + +### Keys + +Keys can be defined at the top of a file, or in a `myst_substitutions` option in `conf.py`. + +{{reuse_key}} + +{{advanced_reuse_key}} + +### File inclusion + +```{include} index.rst + :start-after: include_start + :end-before: include_end +``` + +## Tabs + +````{tabs} +```{group-tab} Tab 1 + +Content Tab 1 +``` + +```{group-tab} Tab 2 +Content Tab 2 +``` +```` + +## Glossary + +```{glossary} + +some term + Definition of the example term. +``` + +{term}`some term` + +## More useful markup + +- ```{versionadded} X.Y +- {abbr}`API (Application Programming Interface)` + +---- + +## Custom extensions + +Related links at the top of the page (surrounded by `---`): + + relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com) + discourse: 12345 + +Terms that should not be checked by the spelling checker: {spellexception}`PurposelyWrong` + +A single-line terminal view that separates input from output: + +```{terminal} + :input: command + :user: root + :host: vampyr + :dir: /home/user/directory/ + +the output +``` + +A multi-line version of the same: + +```{terminal} + :user: root + :host: vampyr + :dir: /home/user/directory/ + +:input: command 1 +output 1 +:input: command 2 +output 2 +``` + +A link to a YouTube video: + +```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0 + :title: Demo +``` diff --git a/docs/doc-cheat-sheet.rst b/docs/doc-cheat-sheet.rst new file mode 100644 index 000000000..c95cb738f --- /dev/null +++ b/docs/doc-cheat-sheet.rst @@ -0,0 +1,281 @@ +:orphan: + +.. _cheat-sheet: + +reStructuredText cheat sheet +============================ + +This file contains the syntax for commonly used reST markup. +Open it in your text editor to quickly copy and paste the markup you need. + +See the `reStructuredText style guide `_ for detailed information and conventions. + +Also see the `Sphinx reStructuredText Primer `_ for more details on reST, and the `Canonical Documentation Style Guide `_ for general style conventions. + +H2 heading +---------- + +H3 heading +~~~~~~~~~~ + +H4 heading +^^^^^^^^^^ + +H5 heading +.......... + +Inline formatting +----------------- + +- :guilabel:`UI element` +- ``code`` +- :file:`file path` +- :command:`command` +- :kbd:`Key` +- *Italic* +- **Bold** + +Code blocks +----------- + +Start a code block:: + + code: + - example: true + +.. code:: + + # Demonstrate a code block + code: + - example: true + +.. code:: yaml + + # Demonstrate a code block + code: + - example: true + +.. _a_section_target: + +Links +----- + +- `Canonical website `_ +- `Canonical website`_ (defined in ``reuse/links.txt`` or at the bottom of the page) +- https:\ //canonical.com/ +- :ref:`a_section_target` +- :ref:`Link text ` +- :doc:`index` +- :doc:`Link text ` + + +Navigation +---------- + +Use the following syntax:: + + .. toctree:: + :hidden: + + sub-page1 + sub-page2 + + +Lists +----- + +1. Step 1 + + - Item 1 + + * Sub-item + - Item 2 + + i. Sub-step 1 + #. Sub-step 2 +#. Step 2 + + a. Sub-step 1 + + - Item + #. Sub-step 2 + +Term 1: + Definition +Term 2: + Definition + +Tables +------ + ++----------------------+------------+ +| Header 1 | Header 2 | ++======================+============+ +| Cell 1 | Cell 2 | +| | | +| Second paragraph | | ++----------------------+------------+ +| Cell 3 | Cell 4 | ++----------------------+------------+ + ++----------------------+------------------+ +| :center:`Header 1` | Header 2 | ++======================+==================+ +| Cell 1 | Cell 2 | +| | | +| Second paragraph | | ++----------------------+------------------+ +| Cell 3 | :center:`Cell 4` | ++----------------------+------------------+ + +.. list-table:: + :header-rows: 1 + + * - Header 1 + - Header 2 + * - Cell 1 + + Second paragraph + - Cell 2 + * - Cell 3 + - Cell 4 + +.. rst-class:: align-center + + +----------------------+------------+ + | Header 1 | Header 2 | + +======================+============+ + | Cell 1 | Cell 2 | + | | | + | Second paragraph | | + +----------------------+------------+ + | Cell 3 | Cell 4 | + +----------------------+------------+ + +.. list-table:: + :header-rows: 1 + :align: center + + * - Header 1 + - Header 2 + * - Cell 1 + + Second paragraph + - Cell 2 + * - Cell 3 + - Cell 4 + +Notes +----- + +.. note:: + A note. + +.. tip:: + A tip. + +.. important:: + Important information + +.. caution:: + This might damage your hardware! + +Images +------ + +.. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png + +.. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png + :width: 100px + :alt: Alt text + + Figure caption + +Reuse +----- + +.. |reuse_key| replace:: This is **included** text. + +|reuse_key| + +.. include:: index.rst + :start-after: include_start + :end-before: include_end + +Tabs +---- + +.. tabs:: + + .. group-tab:: Tab 1 + + Content Tab 1 + + .. group-tab:: Tab 2 + + Content Tab 2 + + +Glossary +-------- + +.. glossary:: + + example term + Definition of the example term. + +:term:`example term` + +More useful markup +------------------ + +- .. versionadded:: X.Y +- | Line 1 + | Line 2 + | Line 3 +- .. This is a comment +- :abbr:`API (Application Programming Interface)` + +---- + +Custom extensions +----------------- + +Related links at the top of the page:: + + :relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com) + :discourse: 12345 + +Terms that should not be checked by the spelling checker: :spellexception:`PurposelyWrong` + +A single-line terminal view that separates input from output: + +.. terminal:: + :input: command + :user: root + :host: vampyr + :dir: /home/user/directory/ + + the output + +A multi-line version of the same: + +.. terminal:: + :user: root + :host: vampyr + :dir: /home/user/directory/ + + :input: command 1 + output 1 + :input: command 2 + output 2 + +A link to a YouTube video: + +.. youtube:: https://www.youtube.com/watch?v=iMLiK1fX4I0 + :title: Demo + + + +.. LINKS +.. _Canonical website: https://canonical.com/ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..317591c5f --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +Starter pack +============ + +This starter pack contains the files you need to quickly set up your Sphinx documentation. + +Before you start, see the information about `Read the Docs at Canonical`_ and the instructions for `How to publish documentation on Read the Docs`_. + +Then, to start setting up your docs, check the :doc:`ReadMe ` for instructions. +The `Example product documentation`_ shows how to set up a Diátaxis structure in Sphinx. + +For quick help on reST or MyST syntax, see the :file:`doc-cheat-sheet.rst.txt` or :file:`doc-cheat-sheet-myst.md.txt` files in the repository. +(Open the files in your text editor; the rendered output is not very useful.) + +More information is available in the `reStructuredText style guide`_. + +.. toctree:: + :hidden: + :maxdepth: 2 + + ReadMe diff --git a/docs/init.sh b/docs/init.sh new file mode 100755 index 000000000..640120395 --- /dev/null +++ b/docs/init.sh @@ -0,0 +1,51 @@ +#!/bin/bash + +# Generate a unique directory name based on timestamp +timestamp=$(date +%Y%m%d%H%M%S) +temp_directory="temp-starter-pack-$timestamp" + +# Ask the user for the installation directory +read -p "Enter the installation directory (e.g., '.' or 'docs'): " install_directory + +# Clone the starter pack repository to the temporary directory +echo "Cloning the starter pack repository..." +git clone --depth 1 https://github.com/canonical/sphinx-docs-starter-pack "$temp_directory" +rm -rf "$temp_directory/.git" + +# Update file contents for the install directory +echo "Updating working directory in workflow files..." +sed -i "s|working-directory:\s*'\.'|working-directory: '$install_directory'|g" "$temp_directory/.github/workflows"/* +echo "Updating .readthedocs.yaml configuration..." +sed -i "s|-\s\s*python3\s\s*.sphinx/build_requirements\.py|- cd '$install_directory' \&\& python3 .sphinx/build_requirements.py|g" "$temp_directory/.readthedocs.yaml" +sed -i "s|configuration:\s*conf\.py|configuration: $install_directory/conf.py|g" "$temp_directory/.readthedocs.yaml" +sed -i "s|requirements:\s*\.sphinx/requirements\.txt|requirements: $install_directory/.sphinx/requirements.txt|g" "$temp_directory/.readthedocs.yaml" + +# Create the specified installation directory if it doesn't exist +if [ ! -d "$install_directory" ]; then + echo "Creating the installation directory: $install_directory" + mkdir -p "$install_directory" +fi + +# Copy the contents of the starter pack repository to the installation directory +echo "Copying contents to the installation directory..." +cp -R "$temp_directory"/* "$temp_directory"/.??* "$install_directory" + +# Move workflow files and configuration +if [ "$install_directory" != "." ]; then + echo "Moving workflow files and configuration..." + if [ ! -d .github/workflows ]; then + mkdir -p .github/workflows + fi + mv "$install_directory/.github/workflows"/* .github/workflows + if [ ! -f .wokeignore ]; then + ln -s "$install_directory/.wokeignore" + else + echo "ACTION REQUIRED: Found a .wokeignore file in the root directory. Include the contents from $install_directory/.wokeignore in this file!" + fi +fi + +# Clean up +echo "Cleaning up..." +rm -rf "$temp_directory" + +echo "Setup completed!" diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 000000000..32bb24529 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/readme.rst b/docs/readme.rst new file mode 100644 index 000000000..aa163fceb --- /dev/null +++ b/docs/readme.rst @@ -0,0 +1,592 @@ +Documentation starter pack +========================== + +*A pre-configured repository to build and publish documentation with Sphinx.* + +The Documentation starter pack includes: + +* a bundled Sphinx_ theme, configuration, and extensions +* support for both reStructuredText (reST) and Markdown +* build checks for links, spelling, and inclusive language +* customisation support layered above a core configuration + +Quickstart guide +---------------- + +An initial set of documentation can be built directly from a clone of this +repository. + +First, clone this repository to a local directory, and change to this +directory: + +.. code-block:: sh + + git clone git@github.com:canonical/sphinx-docs-starter-pack + cd + +Now build the documentation with the following command. This will create a virtual +environment, install the software dependencies, and build the documentation: + +.. code-block:: sh + + make run + +Keep this session running to rebuild the documentation automatically whenever a +file is saved, and open |http://127.0.0.1:8000|_ in a web browser to see the +locally built and hosted HTML. + +To add a new page to the documentation, create a new document called +``reference.rst`` in a text editor and insert the following reST-formatted +``Reference`` heading: + +.. code-block:: rest + + Reference + ========= + +Now save ``reference.rst`` and open ``index.rst``. + +At the bottom of this file, add an indented line containing ``Reference +`` to the end of the ``toctree`` section. This is the navigation +title for the new document and its filename without the ``.rst`` extension. + +The ``toctree`` section will now look like this: + +.. code-block:: rest + + .. toctree:: + :hidden: + :maxdepth: 2 + + ReadMe + Reference + +Save ``index.rst`` and reload |http://127.0.0.1:8000|_. + +The documentation will now show **Reference** added to the navigation and +selecting this will open the new ``reference.rst`` document. + +Contents +-------- + +The remainder of this README is divided into two main parts: *Enable the starter +pack* and *Work with your documentation* post-enablement. + +- `Enable the starter pack`_ + + * `Initialise your repository`_ + + + `Standalone documentation repository`_ + + `Documentation in a code repository`_ + + `Automation`_ + + * `Build the documentation`_ + * `Configure the documentation`_ + + + `Configure the header`_ + + `Activate/deactivate feedback button`_ + + `Configure included extensions`_ + + `Add custom configuration`_ + + * `Change log`_ + +- `Work with your documentation`_ + + * `Install prerequisite software`_ + * `View the documentation`_ + + * `Local checks`_ + + + `Local build`_ + + `Spelling check`_ + + `Inclusive language check`_ + + `Accessibility check`_ + + `Link check`_ + + * `Configure the spelling check`_ + * `Configure the inclusive language check`_ + * `Configure the accessibility check`_ + * `Configure the link check`_ + * `Add redirects`_ + * `Other resources`_ + +Enable the starter pack +----------------------- + +This section is for repository administrators. It shows how to initialise a +repository with the starter pack. Once this is done, documentation contributors +should follow section `Work with your documentation`_. + +**Note:** After setting up your repository with the starter pack, you need to track the changes made to it and manually update your repository with the required files. +The `change log `_ lists the most relevant (and of course all breaking) changes. +We're planning to provide the contents of this repository as an installable package in the future to make updates easier. + +See the `Read the Docs at Canonical `_ and +`How to publish documentation on Read the Docs `_ guides for +instructions on how to get started with Sphinx documentation. + +Initialise your repository +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can either create a standalone documentation project based on this repository or include the files from this repository in a dedicated documentation folder in an existing code repository. The next two sections show the steps needed for each scenario. + +See the `Automation`_ section if you would like to have this done via a shell script. + +Standalone documentation repository +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To create a standalone documentation repository, clone this starter pack +repository, `update the configuration <#configure-the-documentation>`_, and +then commit all files to the documentation repository. + +You don't need to move any files, and you don't need to do any special +configuration on Read the Docs. + +Here is one way to do this for newly-created fictional docs repository +``canonical/alpha-docs``: + +.. code-block:: none + + git clone git@github.com:canonical/sphinx-docs-starter-pack alpha-docs + cd alpha-docs + rm -rf .git + git init + git branch -m main + UPDATE THE CONFIGURATION AND BUILD THE DOCS + git add -A + git commit -m "Import sphinx-docs-starter-pack" + git remote add upstream git@github.com:canonical/alpha-docs + git push -f upstream main + +Documentation in a code repository +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To add documentation to an existing code repository: + +#. create a directory called ``docs`` at the root of the code repository +#. populate the above directory with the contents of the starter pack + repository (with the exception of the ``.git`` directory) +#. copy the file(s) located in the ``docs/.github/workflows`` directory into + the code repository's ``.github/workflows`` directory +#. in the above workflow file(s), change the value of the ``working-directory`` field from ``.`` to ``docs`` +#. create a symbolic link to the ``docs/.wokeignore`` file from the root directory of the code repository +#. in file ``docs/.readthedocs.yaml`` set the following: + + * ``post_checkout: cd docs && python3 .sphinx/build_requirements.py`` + * ``configuration: docs/conf.py`` + * ``requirements: docs/.sphinx/requirements.txt`` + +**Note:** When configuring RTD itself for your project, the setting "Path for +``.readthedocs.yaml``" (under **Advanced Settings**) will need to be given the +value of ``docs/.readthedocs.yaml``. + +Automation +^^^^^^^^^^ + +To automate the initialisation for either scenario ensure you have the following: + +- A GitHub repository where you want to host your documentation, cloned to your local machine. The recommended approach is to host the documentation alongside your code in a ``docs`` folder. But a standalone documentation repository is also an option; in this case, start with an empty repository. +- Git and Bash installed on your system. + +There is a provided ``init.sh`` Bash script that does the following: + +- clones the starter pack GitHub repository +- creates the specified installation directory if necessary +- updates working directory paths in workflow files, and updates configuration paths in the ``.readthedocs.yaml`` file +- copies and moves contents and ``.github`` files from the starter pack to the installation directory +- deletes the cloned repository when it's done + +To use the script: + +#. copy ``init.sh`` to your repository's root directory +#. run the script: ``./init.sh`` +#. enter the installation directory when prompted. For standalone repositories, enter ".". For documentation alongside code, enter the folder where your documentation is (e.g. ``docs``) + +When the script completes, review all changes before committing them. + +Build the documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +The documentation needs to be built in order to be published. This is explained +in more detail in section `Local checks`_ (for contributors), but at this time +you should verify a successful build. Run the following commands from where +your doc files were placed (repository root or the ``docs`` directory): + +.. code-block:: none + + make install + make html + +Configure the documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You must modify some of the default configuration to suit your project. +To simplify keeping your documentation in sync with the starter pack, all custom configuration is located in the ``custom_conf.py`` file. +You should never modify the common ``conf.py`` file. + +Go through all settings in the ``Project information`` section of the ``custom_conf.py`` file and update them for your project. + +See the following sections for further customisation. + +Configure the header +^^^^^^^^^^^^^^^^^^^^ + +By default, the header contains your product tag, product name (taken from the ``project`` setting in the ``custom_conf.py`` file), a link to your product page, and a drop-down menu for "More resources" that contains links to Discourse and GitHub. + +You can change any of those links or add further links to the "More resources" drop-down by editing the ``.sphinx/_templates/header.html`` file. +For example, you might want to add links to announcements, tutorials, getting started guides, or videos that are not part of the documentation. + +Activate/deactivate feedback button +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A feedback button is included by default, which appears at the top of each page +in the documentation. It redirects users to your GitHub issues page, and +populates an issue for them with details of the page they were on when they +clicked the button. + +If your project does not use GitHub issues, set the ``github_issues`` variable +in the ``custom_conf.py`` file to an empty value to disable both the feedback button +and the issue link in the footer. +If you want to deactivate only the feedback button, but keep the link in the +footer, set ``disable_feedback_button`` in the ``custom_conf.py`` file to ``True``. + +Configure included extensions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The starter pack includes a set of extensions that are useful for all documentation sets. +They are pre-configured as needed, but you can customise their configuration in the ``custom_conf.py`` file. + +The following extensions are always included: + +- |sphinx-design|_ +- |sphinx_copybutton|_ +- |sphinxcontrib.jquery|_ + +The following extensions will automatically be included based on the configuration in the ``custom_conf.py`` file: + +- |sphinx_tabs.tabs|_ +- |sphinx_reredirects|_ +- |sphinxext.opengraph|_ +- |lxd-sphinx-extensions|_ (``youtube-links``, ``related-links``, ``custom-rst-roles``, and ``terminal-output``) +- |myst_parser|_ +- |notfound.extension|_ + +You can add further extensions in the ``custom_extensions`` variable in ``custom_conf.py``. + +Add custom configuration +^^^^^^^^^^^^^^^^^^^^^^^^ + +To add custom configurations for your project, see the ``Additions to default configuration`` and ``Additional configuration`` sections in the ``custom_conf.py`` file. +These can be used to extend or override the common configuration, or to define additional configuration that is not covered by the common ``conf.py`` file. + +The following links can help you with additional configuration: + +- `Sphinx configuration`_ +- `Sphinx extensions`_ +- `Furo documentation`_ (Furo is the Sphinx theme we use as our base.) + +Add page-specific configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can override some global configuration for specific pages. + +For example, you can configure whether to display Previous/Next buttons at the bottom of pages in the ``custom_conf.py`` file. +You can then override this default setting for a specific page (a common use case for this is to turn off the Previous/Next buttons by default, but display them in a multi-page tutorial). + +To do so, add `file-wide metadata`_ at the top of a page. +See the following examples for how to enable Previous/Next buttons for one page: + +reST + .. code-block:: + + :sequential_nav: both + + [Page contents] + +MyST + .. code-block:: + + --- + sequential_nav: both + --- + + [Page contents] + +Possible values for the ``sequential_nav`` field are ``none``, ``prev``, ``next``, and ``both``. +See the ``custom_conf.py`` file for more information. + +Another example for page-specific configuration is the ``hide-toc`` field (provided by `Furo `_), which can be used to hide the page-internal table of content. +See `Hiding Contents sidebar`_. + +Change log +~~~~~~~~~~ + +See the `change log `_ for a list of relevant changes to the starter pack. + +Work with your documentation +---------------------------- + +This section is for documentation contributors. It assumes that the current +repository has been initialised with the starter pack as described in +section `Enable the starter pack`_. + +There are make targets defined in the ``Makefile`` that do various things. To +get started, we will: + +* install prerequisite software +* view the documentation + +Install prerequisite software +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before you start, make sure you have ``make`` and ``python3`` on your system: + +.. code-block:: none + + sudo apt update + sudo apt install make python3 + +Some `validation tools <#local-checks>`_ won't be available by default; +to install them, you need ``snap`` and ``npm``: + +.. code-block:: none + + sudo apt install npm snapd + +To install the core prerequisites: + +.. code-block:: none + + make install + +This will create the required software list (``.sphinx/requirements.txt``), +which is used to create a virtual environment (``.sphinx/venv``) and install +dependency software within it. + +To install the validation tools: + +.. code-block:: none + + make woke-install + make pa11y-install + +You can add further Python modules to the required software list +(``.sphinx/requirements.txt``) in the ``custom_required_modules`` variable +in the ``custom_conf.py`` file. + +**Note**: +By default, the starter pack uses the latest compatible version of all tools and does not pin its requirements. +This might change temporarily if there is an incompatibility with a new tool version. +There is therefore no need in using a tool like Renovate to automatically update the requirements. + +View the documentation +~~~~~~~~~~~~~~~~~~~~~~ + +To view the documentation: + +.. code-block:: none + + make run + +This will do several things: + +* activate the virtual environment +* build the documentation +* serve the documentation on **127.0.0.1:8000** +* rebuild the documentation each time a file is saved +* send a reload page signal to the browser when the documentation is rebuilt + +The ``run`` target is therefore very convenient when preparing to submit a +change to the documentation. + +.. note:: + + If you encounter the error ``locale.Error: unsupported locale setting`` when activating the Python virtual environment, include the environment variable in the command and try again: ``LC_ALL=en_US.UTF-8 make run`` + +Local checks +~~~~~~~~~~~~ + +Before committing and pushing changes, it's a good practice to run various checks locally to catch issues early in the development process. + +Local build +^^^^^^^^^^^ + +Run a clean build of the docs to surface any build errors that would occur in RTD: + +.. code-block:: none + + make clean-doc + make html + +Spelling check +^^^^^^^^^^^^^^ + +Ensure there are no spelling errors in the documentation: + +.. code-block:: shell + + make spelling + +Inclusive language check +^^^^^^^^^^^^^^^^^^^^^^^^ + +Ensure the documentation uses inclusive language: + +.. code-block:: shell + + make woke + +Accessibility check +^^^^^^^^^^^^^^^^^^^ + +Look for accessibility issues in rendered documentation: + +.. code-block:: shell + + make pa11y + +Link check +^^^^^^^^^^ + +Validate links within the documentation: + +.. code-block:: shell + + make linkcheck + +Configure the spelling check +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The spelling check uses ``aspell``. +Its configuration is located in the ``.sphinx/spellingcheck.yaml`` file. + +To add exceptions for words flagged by the spelling check, edit the ``.custom_wordlist.txt`` file. +You shouldn't edit ``.wordlist.txt``, because this file is maintained and updated centrally and contains words that apply across all projects. + +Configure the inclusive language check +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, the inclusive language check is applied only to reST files located +under the documentation directory (usually ``docs``). To check Markdown files, +for example, or to use a location other than the ``docs`` sub-tree, you must +change how the ``woke`` tool is invoked from within ``docs/Makefile`` (see +the `woke User Guide `_ for help). + +Inclusive language check exemptions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some circumstances may require you to use some non-inclusive words. In such +cases you will need to create check-exemptions for them. + +This page provides an overview of two inclusive language check exemption +methods for files written in reST format. See the `woke documentation`_ for +full coverage. + +Exempt a word +............. + +To exempt an individual word, place a custom ``none`` role (defined in the +``canonical-sphinx-extensions`` Sphinx extension) anywhere on the line +containing the word in question. The role syntax is: + +.. code-block:: none + + :none:`wokeignore:rule=,` + +For instance: + +.. code-block:: none + + This is your text. The word in question is here: whitelist. More text. :none:`wokeignore:rule=whitelist,` + +To exempt an element of a URL, it is recommended to use the standard reST +method of placing links at the bottom of the page (or in a separate file). In +this case, a comment line is placed immediately above the URL line. The comment +syntax is: + +.. code-block:: none + + .. wokeignore:rule= + +Here is an example where a URL element contains the string "master": :none:`wokeignore:rule=master,` + +.. code-block:: none + + .. LINKS + .. wokeignore:rule=master + .. _link definition: https://some-external-site.io/master/some-page.html + +You can now refer to the label ``link definition_`` in the body of the text. + +Exempt an entire file +..................... + +A more drastic solution is to make an exemption for the contents of an entire +file. For example, to exempt file ``docs/foo/bar.rst`` add the following line +to file ``.wokeignore``: + +.. code-block:: none + + foo/bar.rst + +Configure the accessibility check +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``pa11y.json`` file at the starter pack root provides basic defaults; to +browse the available settings and options, see ``pa11y``'s `README +`_ on GitHub. + + +Configure the link check +~~~~~~~~~~~~~~~~~~~~~~~~ + +If you have links in the documentation that you don't want to be checked (for +example, because they are local links or give random errors even though they +work), you can add them to the ``linkcheck_ignore`` variable in the ``custom_conf.py`` file. + +Add redirects +~~~~~~~~~~~~~ + +You can add redirects to make sure existing links and bookmarks continue working when you move files around. +To do so, specify the old and new paths in the ``redirects`` setting of the ``custom_conf.py`` file. + +Other resources +~~~~~~~~~~~~~~~ + +- `Example product documentation `_ +- `Example product documentation repository `_ + +.. LINKS + +.. wokeignore:rule=master +.. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html +.. wokeignore:rule=master +.. _`Sphinx extensions`: https://www.sphinx-doc.org/en/master/usage/extensions/index.html +.. wokeignore:rule=master +.. _`file-wide metadata`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html +.. _`Furo documentation`: https://pradyunsg.me/furo/quickstart/ +.. _`Hiding Contents sidebar`: https://pradyunsg.me/furo/customisation/toc/ +.. _`Sphinx`: https://www.sphinx-doc.org/ + +.. |http://127.0.0.1:8000| replace:: ``http://127.0.0.1:8000`` +.. _`http://127.0.0.1:8000`: http://127.0.0.1:8000 +.. |sphinx-design| replace:: ``sphinx-design`` +.. _sphinx-design: https://sphinx-design.readthedocs.io/en/latest/ +.. |sphinx_tabs.tabs| replace:: ``sphinx_tabs.tabs`` +.. _sphinx_tabs.tabs: https://sphinx-tabs.readthedocs.io/en/latest/ +.. |sphinx_reredirects| replace:: ``sphinx_reredirects`` +.. _sphinx_reredirects: https://documatt.gitlab.io/sphinx-reredirects/ +.. |lxd-sphinx-extensions| replace:: ``lxd-sphinx-extensions`` +.. _lxd-sphinx-extensions: https://github.com/canonical/lxd-sphinx-extensions#lxd-sphinx-extensions +.. |sphinx_copybutton| replace:: ``sphinx_copybutton`` +.. _sphinx_copybutton: https://sphinx-copybutton.readthedocs.io/en/latest/ +.. |sphinxext.opengraph| replace:: ``sphinxext.opengraph`` +.. _sphinxext.opengraph: https://sphinxext-opengraph.readthedocs.io/en/latest/ +.. |myst_parser| replace:: ``myst_parser`` +.. _myst_parser: https://myst-parser.readthedocs.io/en/latest/ +.. |sphinxcontrib.jquery| replace:: ``sphinxcontrib.jquery`` +.. _sphinxcontrib.jquery: https://github.com/sphinx-contrib/jquery/ +.. |notfound.extension| replace:: ``notfound.extension`` +.. _notfound.extension: https://sphinx-notfound-page.readthedocs.io/en/latest/ + +.. _woke documentation: https://docs.getwoke.tech/ignore diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt new file mode 100644 index 000000000..04cfff56e --- /dev/null +++ b/docs/reuse/links.txt @@ -0,0 +1,4 @@ +.. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/ +.. _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/ From 37f58496cbac4c609f4b7850bad43a011dd23fc5 Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Thu, 23 May 2024 11:01:57 +0800 Subject: [PATCH 02/14] chore: update readthedocs docs path --- docs/.readthedocs.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml index 91ca074b4..c29791f95 100644 --- a/docs/.readthedocs.yaml +++ b/docs/.readthedocs.yaml @@ -12,7 +12,7 @@ build: python: "3.11" jobs: post_checkout: - - python3 .sphinx/build_requirements.py + - python3 docs/.sphinx/build_requirements.py apt_packages: - distro-info @@ -29,4 +29,4 @@ formats: # Optionally declare the Python requirements required to build your docs python: install: - - requirements: .sphinx/requirements.txt + - requirements: docs/.sphinx/requirements.txt From 5dbba809d4b8fa97e61a3e82c82ae4b54fe7b4ee Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Thu, 23 May 2024 11:05:20 +0800 Subject: [PATCH 03/14] chore: move readthedocs location --- docs/.readthedocs.yaml => .readthedocs.yaml | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/.readthedocs.yaml => .readthedocs.yaml (100%) diff --git a/docs/.readthedocs.yaml b/.readthedocs.yaml similarity index 100% rename from docs/.readthedocs.yaml rename to .readthedocs.yaml From 39dc116cb44d98c68313836b20835371877f92a8 Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Thu, 23 May 2024 11:09:47 +0800 Subject: [PATCH 04/14] chore: customize --- .github/workflows/automatic-doc-checks.yml | 2 +- .readthedocs.yaml => docs/.readthedocs.yaml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) rename .readthedocs.yaml => docs/.readthedocs.yaml (88%) diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml index a6eb0ab72..3a4fe5e23 100644 --- a/.github/workflows/automatic-doc-checks.yml +++ b/.github/workflows/automatic-doc-checks.yml @@ -13,4 +13,4 @@ jobs: documentation-checks: uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main with: - working-directory: '.' \ No newline at end of file + working-directory: 'docs' \ No newline at end of file diff --git a/.readthedocs.yaml b/docs/.readthedocs.yaml similarity index 88% rename from .readthedocs.yaml rename to docs/.readthedocs.yaml index c29791f95..12f286571 100644 --- a/.readthedocs.yaml +++ b/docs/.readthedocs.yaml @@ -12,14 +12,14 @@ build: python: "3.11" jobs: post_checkout: - - python3 docs/.sphinx/build_requirements.py + - cd docs && python3 .sphinx/build_requirements.py apt_packages: - distro-info # Build documentation in the docs/ directory with Sphinx sphinx: builder: dirhtml - configuration: conf.py + configuration: docs/conf.py fail_on_warning: true # If using Sphinx, optionally build your docs in additional formats such as PDF From 058e8619d482fb84e540bc255a682fe76405dff2 Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Thu, 23 May 2024 11:13:02 +0800 Subject: [PATCH 05/14] chore: fix conf bug --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 16f8522f8..a2581becd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -190,7 +190,7 @@ def get_contributors_for_file(github_url, github_folder, pagename, page_source_suffix, display_contributors_since=None): filename = f"{pagename}{page_source_suffix}" paths=html_context['github_folder'][1:] + filename - repo = Repo(".") + repo = Repo("../") since = display_contributors_since if display_contributors_since and display_contributors_since.strip() else None commits = repo.iter_commits(paths=paths, since=since) From cc722f84f65511fc9e1fd7ed93f20eaeb153f6ea Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Thu, 23 May 2024 13:33:34 +0800 Subject: [PATCH 06/14] chore: adding empty new line at the end of the workflow from starter pack --- .github/workflows/automatic-doc-checks.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml index 3a4fe5e23..cba712e5a 100644 --- a/.github/workflows/automatic-doc-checks.yml +++ b/.github/workflows/automatic-doc-checks.yml @@ -13,4 +13,4 @@ jobs: documentation-checks: uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main with: - working-directory: 'docs' \ No newline at end of file + working-directory: 'docs' From 57ed89865fff4e59d498bc76b2667184b32e7274 Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Fri, 24 May 2024 08:59:49 +0800 Subject: [PATCH 07/14] chore: remove unnecessary files from the starter pack --- docs/doc-cheat-sheet-myst.md | 257 --------------- docs/doc-cheat-sheet.rst | 281 ----------------- docs/init.sh | 51 --- docs/make.bat | 35 --- docs/readme.rst | 592 ----------------------------------- 5 files changed, 1216 deletions(-) delete mode 100644 docs/doc-cheat-sheet-myst.md delete mode 100644 docs/doc-cheat-sheet.rst delete mode 100755 docs/init.sh delete mode 100644 docs/make.bat delete mode 100644 docs/readme.rst diff --git a/docs/doc-cheat-sheet-myst.md b/docs/doc-cheat-sheet-myst.md deleted file mode 100644 index 11731d804..000000000 --- a/docs/doc-cheat-sheet-myst.md +++ /dev/null @@ -1,257 +0,0 @@ ---- -orphan: true -myst: - substitutions: - reuse_key: "This is **included** text." - advanced_reuse_key: "This is a substitution that includes a code block: - ``` - code block - ```" ---- - -(cheat-sheet-myst)= -# Markdown/MyST cheat sheet - -This file contains the syntax for commonly used Markdown and MyST markup. -Open it in your text editor to quickly copy and paste the markup you need. - -Also see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/index.html) for detailed information, and the [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) for general style conventions. - -## H2 heading - -### H3 heading - -#### H4 heading - -##### H5 heading - -## Inline formatting - -- {guilabel}`UI element` -- `code` -- {command}`command` -- {kbd}`Key` -- *Italic* -- **Bold** - -## Code blocks - -Start a code block: - - code: - - example: true - -``` -# Demonstrate a code block -code: - - example: true -``` - -```yaml -# Demonstrate a code block -code: - - example: true -``` - -(a_section_target_myst)= -## Links - -- [Canonical website](https://canonical.com/) -- https://canonical.com/ -- {ref}`a_section_target_myst` -- {ref}`Link text ` -- {doc}`index` -- {doc}`Link text ` - - -## Navigation - -Use the following syntax:: - - ```{toctree} - :hidden: - - sub-page1 - sub-page2 - ``` - -## Lists - -1. Step 1 - - Item 1 - * Sub-item - - Item 2 - 1. Sub-step 1 - 1. Sub-step 2 -1. Step 2 - 1. Sub-step 1 - - Item - 1. Sub-step 2 - -Term 1 -: Definition - -Term 2 -: Definition - -## Tables - -## Markdown tables - -| Header 1 | Header 2 | -|------------------------------------|----------| -| Cell 1
Second paragraph | Cell 2 | -| Cell 3 | Cell 4 | - -Centred: - -| Header 1 | Header 2 | -|:----------------------------------:|:--------:| -| Cell 1
Second paragraph | Cell 2 | -| Cell 3 | Cell 4 | - -## List tables - -```{list-table} - :header-rows: 1 - -* - Header 1 - - Header 2 -* - Cell 1 - - Second paragraph - - Cell 2 -* - Cell 3 - - Cell 4 -``` - -Centred: - -```{list-table} - :header-rows: 1 - :align: center - -* - Header 1 - - Header 2 -* - Cell 1 - - Second paragraph - - Cell 2 -* - Cell 3 - - Cell 4 -``` - -## Notes - -```{note} -A note. -``` - -```{tip} -A tip. -``` - -```{important} -Important information -``` - -```{caution} -This might damage your hardware! -``` - -## Images - -![Alt text](https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png) - -```{figure} https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - :width: 100px - :alt: Alt text - - Figure caption -``` - -## Reuse - -### Keys - -Keys can be defined at the top of a file, or in a `myst_substitutions` option in `conf.py`. - -{{reuse_key}} - -{{advanced_reuse_key}} - -### File inclusion - -```{include} index.rst - :start-after: include_start - :end-before: include_end -``` - -## Tabs - -````{tabs} -```{group-tab} Tab 1 - -Content Tab 1 -``` - -```{group-tab} Tab 2 -Content Tab 2 -``` -```` - -## Glossary - -```{glossary} - -some term - Definition of the example term. -``` - -{term}`some term` - -## More useful markup - -- ```{versionadded} X.Y -- {abbr}`API (Application Programming Interface)` - ----- - -## Custom extensions - -Related links at the top of the page (surrounded by `---`): - - relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com) - discourse: 12345 - -Terms that should not be checked by the spelling checker: {spellexception}`PurposelyWrong` - -A single-line terminal view that separates input from output: - -```{terminal} - :input: command - :user: root - :host: vampyr - :dir: /home/user/directory/ - -the output -``` - -A multi-line version of the same: - -```{terminal} - :user: root - :host: vampyr - :dir: /home/user/directory/ - -:input: command 1 -output 1 -:input: command 2 -output 2 -``` - -A link to a YouTube video: - -```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0 - :title: Demo -``` diff --git a/docs/doc-cheat-sheet.rst b/docs/doc-cheat-sheet.rst deleted file mode 100644 index c95cb738f..000000000 --- a/docs/doc-cheat-sheet.rst +++ /dev/null @@ -1,281 +0,0 @@ -:orphan: - -.. _cheat-sheet: - -reStructuredText cheat sheet -============================ - -This file contains the syntax for commonly used reST markup. -Open it in your text editor to quickly copy and paste the markup you need. - -See the `reStructuredText style guide `_ for detailed information and conventions. - -Also see the `Sphinx reStructuredText Primer `_ for more details on reST, and the `Canonical Documentation Style Guide `_ for general style conventions. - -H2 heading ----------- - -H3 heading -~~~~~~~~~~ - -H4 heading -^^^^^^^^^^ - -H5 heading -.......... - -Inline formatting ------------------ - -- :guilabel:`UI element` -- ``code`` -- :file:`file path` -- :command:`command` -- :kbd:`Key` -- *Italic* -- **Bold** - -Code blocks ------------ - -Start a code block:: - - code: - - example: true - -.. code:: - - # Demonstrate a code block - code: - - example: true - -.. code:: yaml - - # Demonstrate a code block - code: - - example: true - -.. _a_section_target: - -Links ------ - -- `Canonical website `_ -- `Canonical website`_ (defined in ``reuse/links.txt`` or at the bottom of the page) -- https:\ //canonical.com/ -- :ref:`a_section_target` -- :ref:`Link text ` -- :doc:`index` -- :doc:`Link text ` - - -Navigation ----------- - -Use the following syntax:: - - .. toctree:: - :hidden: - - sub-page1 - sub-page2 - - -Lists ------ - -1. Step 1 - - - Item 1 - - * Sub-item - - Item 2 - - i. Sub-step 1 - #. Sub-step 2 -#. Step 2 - - a. Sub-step 1 - - - Item - #. Sub-step 2 - -Term 1: - Definition -Term 2: - Definition - -Tables ------- - -+----------------------+------------+ -| Header 1 | Header 2 | -+======================+============+ -| Cell 1 | Cell 2 | -| | | -| Second paragraph | | -+----------------------+------------+ -| Cell 3 | Cell 4 | -+----------------------+------------+ - -+----------------------+------------------+ -| :center:`Header 1` | Header 2 | -+======================+==================+ -| Cell 1 | Cell 2 | -| | | -| Second paragraph | | -+----------------------+------------------+ -| Cell 3 | :center:`Cell 4` | -+----------------------+------------------+ - -.. list-table:: - :header-rows: 1 - - * - Header 1 - - Header 2 - * - Cell 1 - - Second paragraph - - Cell 2 - * - Cell 3 - - Cell 4 - -.. rst-class:: align-center - - +----------------------+------------+ - | Header 1 | Header 2 | - +======================+============+ - | Cell 1 | Cell 2 | - | | | - | Second paragraph | | - +----------------------+------------+ - | Cell 3 | Cell 4 | - +----------------------+------------+ - -.. list-table:: - :header-rows: 1 - :align: center - - * - Header 1 - - Header 2 - * - Cell 1 - - Second paragraph - - Cell 2 - * - Cell 3 - - Cell 4 - -Notes ------ - -.. note:: - A note. - -.. tip:: - A tip. - -.. important:: - Important information - -.. caution:: - This might damage your hardware! - -Images ------- - -.. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - -.. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - :width: 100px - :alt: Alt text - - Figure caption - -Reuse ------ - -.. |reuse_key| replace:: This is **included** text. - -|reuse_key| - -.. include:: index.rst - :start-after: include_start - :end-before: include_end - -Tabs ----- - -.. tabs:: - - .. group-tab:: Tab 1 - - Content Tab 1 - - .. group-tab:: Tab 2 - - Content Tab 2 - - -Glossary --------- - -.. glossary:: - - example term - Definition of the example term. - -:term:`example term` - -More useful markup ------------------- - -- .. versionadded:: X.Y -- | Line 1 - | Line 2 - | Line 3 -- .. This is a comment -- :abbr:`API (Application Programming Interface)` - ----- - -Custom extensions ------------------ - -Related links at the top of the page:: - - :relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com) - :discourse: 12345 - -Terms that should not be checked by the spelling checker: :spellexception:`PurposelyWrong` - -A single-line terminal view that separates input from output: - -.. terminal:: - :input: command - :user: root - :host: vampyr - :dir: /home/user/directory/ - - the output - -A multi-line version of the same: - -.. terminal:: - :user: root - :host: vampyr - :dir: /home/user/directory/ - - :input: command 1 - output 1 - :input: command 2 - output 2 - -A link to a YouTube video: - -.. youtube:: https://www.youtube.com/watch?v=iMLiK1fX4I0 - :title: Demo - - - -.. LINKS -.. _Canonical website: https://canonical.com/ diff --git a/docs/init.sh b/docs/init.sh deleted file mode 100755 index 640120395..000000000 --- a/docs/init.sh +++ /dev/null @@ -1,51 +0,0 @@ -#!/bin/bash - -# Generate a unique directory name based on timestamp -timestamp=$(date +%Y%m%d%H%M%S) -temp_directory="temp-starter-pack-$timestamp" - -# Ask the user for the installation directory -read -p "Enter the installation directory (e.g., '.' or 'docs'): " install_directory - -# Clone the starter pack repository to the temporary directory -echo "Cloning the starter pack repository..." -git clone --depth 1 https://github.com/canonical/sphinx-docs-starter-pack "$temp_directory" -rm -rf "$temp_directory/.git" - -# Update file contents for the install directory -echo "Updating working directory in workflow files..." -sed -i "s|working-directory:\s*'\.'|working-directory: '$install_directory'|g" "$temp_directory/.github/workflows"/* -echo "Updating .readthedocs.yaml configuration..." -sed -i "s|-\s\s*python3\s\s*.sphinx/build_requirements\.py|- cd '$install_directory' \&\& python3 .sphinx/build_requirements.py|g" "$temp_directory/.readthedocs.yaml" -sed -i "s|configuration:\s*conf\.py|configuration: $install_directory/conf.py|g" "$temp_directory/.readthedocs.yaml" -sed -i "s|requirements:\s*\.sphinx/requirements\.txt|requirements: $install_directory/.sphinx/requirements.txt|g" "$temp_directory/.readthedocs.yaml" - -# Create the specified installation directory if it doesn't exist -if [ ! -d "$install_directory" ]; then - echo "Creating the installation directory: $install_directory" - mkdir -p "$install_directory" -fi - -# Copy the contents of the starter pack repository to the installation directory -echo "Copying contents to the installation directory..." -cp -R "$temp_directory"/* "$temp_directory"/.??* "$install_directory" - -# Move workflow files and configuration -if [ "$install_directory" != "." ]; then - echo "Moving workflow files and configuration..." - if [ ! -d .github/workflows ]; then - mkdir -p .github/workflows - fi - mv "$install_directory/.github/workflows"/* .github/workflows - if [ ! -f .wokeignore ]; then - ln -s "$install_directory/.wokeignore" - else - echo "ACTION REQUIRED: Found a .wokeignore file in the root directory. Include the contents from $install_directory/.wokeignore in this file!" - fi -fi - -# Clean up -echo "Cleaning up..." -rm -rf "$temp_directory" - -echo "Setup completed!" diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 32bb24529..000000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/readme.rst b/docs/readme.rst deleted file mode 100644 index aa163fceb..000000000 --- a/docs/readme.rst +++ /dev/null @@ -1,592 +0,0 @@ -Documentation starter pack -========================== - -*A pre-configured repository to build and publish documentation with Sphinx.* - -The Documentation starter pack includes: - -* a bundled Sphinx_ theme, configuration, and extensions -* support for both reStructuredText (reST) and Markdown -* build checks for links, spelling, and inclusive language -* customisation support layered above a core configuration - -Quickstart guide ----------------- - -An initial set of documentation can be built directly from a clone of this -repository. - -First, clone this repository to a local directory, and change to this -directory: - -.. code-block:: sh - - git clone git@github.com:canonical/sphinx-docs-starter-pack - cd - -Now build the documentation with the following command. This will create a virtual -environment, install the software dependencies, and build the documentation: - -.. code-block:: sh - - make run - -Keep this session running to rebuild the documentation automatically whenever a -file is saved, and open |http://127.0.0.1:8000|_ in a web browser to see the -locally built and hosted HTML. - -To add a new page to the documentation, create a new document called -``reference.rst`` in a text editor and insert the following reST-formatted -``Reference`` heading: - -.. code-block:: rest - - Reference - ========= - -Now save ``reference.rst`` and open ``index.rst``. - -At the bottom of this file, add an indented line containing ``Reference -`` to the end of the ``toctree`` section. This is the navigation -title for the new document and its filename without the ``.rst`` extension. - -The ``toctree`` section will now look like this: - -.. code-block:: rest - - .. toctree:: - :hidden: - :maxdepth: 2 - - ReadMe - Reference - -Save ``index.rst`` and reload |http://127.0.0.1:8000|_. - -The documentation will now show **Reference** added to the navigation and -selecting this will open the new ``reference.rst`` document. - -Contents --------- - -The remainder of this README is divided into two main parts: *Enable the starter -pack* and *Work with your documentation* post-enablement. - -- `Enable the starter pack`_ - - * `Initialise your repository`_ - - + `Standalone documentation repository`_ - + `Documentation in a code repository`_ - + `Automation`_ - - * `Build the documentation`_ - * `Configure the documentation`_ - - + `Configure the header`_ - + `Activate/deactivate feedback button`_ - + `Configure included extensions`_ - + `Add custom configuration`_ - - * `Change log`_ - -- `Work with your documentation`_ - - * `Install prerequisite software`_ - * `View the documentation`_ - - * `Local checks`_ - - + `Local build`_ - + `Spelling check`_ - + `Inclusive language check`_ - + `Accessibility check`_ - + `Link check`_ - - * `Configure the spelling check`_ - * `Configure the inclusive language check`_ - * `Configure the accessibility check`_ - * `Configure the link check`_ - * `Add redirects`_ - * `Other resources`_ - -Enable the starter pack ------------------------ - -This section is for repository administrators. It shows how to initialise a -repository with the starter pack. Once this is done, documentation contributors -should follow section `Work with your documentation`_. - -**Note:** After setting up your repository with the starter pack, you need to track the changes made to it and manually update your repository with the required files. -The `change log `_ lists the most relevant (and of course all breaking) changes. -We're planning to provide the contents of this repository as an installable package in the future to make updates easier. - -See the `Read the Docs at Canonical `_ and -`How to publish documentation on Read the Docs `_ guides for -instructions on how to get started with Sphinx documentation. - -Initialise your repository -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can either create a standalone documentation project based on this repository or include the files from this repository in a dedicated documentation folder in an existing code repository. The next two sections show the steps needed for each scenario. - -See the `Automation`_ section if you would like to have this done via a shell script. - -Standalone documentation repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To create a standalone documentation repository, clone this starter pack -repository, `update the configuration <#configure-the-documentation>`_, and -then commit all files to the documentation repository. - -You don't need to move any files, and you don't need to do any special -configuration on Read the Docs. - -Here is one way to do this for newly-created fictional docs repository -``canonical/alpha-docs``: - -.. code-block:: none - - git clone git@github.com:canonical/sphinx-docs-starter-pack alpha-docs - cd alpha-docs - rm -rf .git - git init - git branch -m main - UPDATE THE CONFIGURATION AND BUILD THE DOCS - git add -A - git commit -m "Import sphinx-docs-starter-pack" - git remote add upstream git@github.com:canonical/alpha-docs - git push -f upstream main - -Documentation in a code repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To add documentation to an existing code repository: - -#. create a directory called ``docs`` at the root of the code repository -#. populate the above directory with the contents of the starter pack - repository (with the exception of the ``.git`` directory) -#. copy the file(s) located in the ``docs/.github/workflows`` directory into - the code repository's ``.github/workflows`` directory -#. in the above workflow file(s), change the value of the ``working-directory`` field from ``.`` to ``docs`` -#. create a symbolic link to the ``docs/.wokeignore`` file from the root directory of the code repository -#. in file ``docs/.readthedocs.yaml`` set the following: - - * ``post_checkout: cd docs && python3 .sphinx/build_requirements.py`` - * ``configuration: docs/conf.py`` - * ``requirements: docs/.sphinx/requirements.txt`` - -**Note:** When configuring RTD itself for your project, the setting "Path for -``.readthedocs.yaml``" (under **Advanced Settings**) will need to be given the -value of ``docs/.readthedocs.yaml``. - -Automation -^^^^^^^^^^ - -To automate the initialisation for either scenario ensure you have the following: - -- A GitHub repository where you want to host your documentation, cloned to your local machine. The recommended approach is to host the documentation alongside your code in a ``docs`` folder. But a standalone documentation repository is also an option; in this case, start with an empty repository. -- Git and Bash installed on your system. - -There is a provided ``init.sh`` Bash script that does the following: - -- clones the starter pack GitHub repository -- creates the specified installation directory if necessary -- updates working directory paths in workflow files, and updates configuration paths in the ``.readthedocs.yaml`` file -- copies and moves contents and ``.github`` files from the starter pack to the installation directory -- deletes the cloned repository when it's done - -To use the script: - -#. copy ``init.sh`` to your repository's root directory -#. run the script: ``./init.sh`` -#. enter the installation directory when prompted. For standalone repositories, enter ".". For documentation alongside code, enter the folder where your documentation is (e.g. ``docs``) - -When the script completes, review all changes before committing them. - -Build the documentation -~~~~~~~~~~~~~~~~~~~~~~~ - -The documentation needs to be built in order to be published. This is explained -in more detail in section `Local checks`_ (for contributors), but at this time -you should verify a successful build. Run the following commands from where -your doc files were placed (repository root or the ``docs`` directory): - -.. code-block:: none - - make install - make html - -Configure the documentation -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You must modify some of the default configuration to suit your project. -To simplify keeping your documentation in sync with the starter pack, all custom configuration is located in the ``custom_conf.py`` file. -You should never modify the common ``conf.py`` file. - -Go through all settings in the ``Project information`` section of the ``custom_conf.py`` file and update them for your project. - -See the following sections for further customisation. - -Configure the header -^^^^^^^^^^^^^^^^^^^^ - -By default, the header contains your product tag, product name (taken from the ``project`` setting in the ``custom_conf.py`` file), a link to your product page, and a drop-down menu for "More resources" that contains links to Discourse and GitHub. - -You can change any of those links or add further links to the "More resources" drop-down by editing the ``.sphinx/_templates/header.html`` file. -For example, you might want to add links to announcements, tutorials, getting started guides, or videos that are not part of the documentation. - -Activate/deactivate feedback button -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A feedback button is included by default, which appears at the top of each page -in the documentation. It redirects users to your GitHub issues page, and -populates an issue for them with details of the page they were on when they -clicked the button. - -If your project does not use GitHub issues, set the ``github_issues`` variable -in the ``custom_conf.py`` file to an empty value to disable both the feedback button -and the issue link in the footer. -If you want to deactivate only the feedback button, but keep the link in the -footer, set ``disable_feedback_button`` in the ``custom_conf.py`` file to ``True``. - -Configure included extensions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The starter pack includes a set of extensions that are useful for all documentation sets. -They are pre-configured as needed, but you can customise their configuration in the ``custom_conf.py`` file. - -The following extensions are always included: - -- |sphinx-design|_ -- |sphinx_copybutton|_ -- |sphinxcontrib.jquery|_ - -The following extensions will automatically be included based on the configuration in the ``custom_conf.py`` file: - -- |sphinx_tabs.tabs|_ -- |sphinx_reredirects|_ -- |sphinxext.opengraph|_ -- |lxd-sphinx-extensions|_ (``youtube-links``, ``related-links``, ``custom-rst-roles``, and ``terminal-output``) -- |myst_parser|_ -- |notfound.extension|_ - -You can add further extensions in the ``custom_extensions`` variable in ``custom_conf.py``. - -Add custom configuration -^^^^^^^^^^^^^^^^^^^^^^^^ - -To add custom configurations for your project, see the ``Additions to default configuration`` and ``Additional configuration`` sections in the ``custom_conf.py`` file. -These can be used to extend or override the common configuration, or to define additional configuration that is not covered by the common ``conf.py`` file. - -The following links can help you with additional configuration: - -- `Sphinx configuration`_ -- `Sphinx extensions`_ -- `Furo documentation`_ (Furo is the Sphinx theme we use as our base.) - -Add page-specific configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can override some global configuration for specific pages. - -For example, you can configure whether to display Previous/Next buttons at the bottom of pages in the ``custom_conf.py`` file. -You can then override this default setting for a specific page (a common use case for this is to turn off the Previous/Next buttons by default, but display them in a multi-page tutorial). - -To do so, add `file-wide metadata`_ at the top of a page. -See the following examples for how to enable Previous/Next buttons for one page: - -reST - .. code-block:: - - :sequential_nav: both - - [Page contents] - -MyST - .. code-block:: - - --- - sequential_nav: both - --- - - [Page contents] - -Possible values for the ``sequential_nav`` field are ``none``, ``prev``, ``next``, and ``both``. -See the ``custom_conf.py`` file for more information. - -Another example for page-specific configuration is the ``hide-toc`` field (provided by `Furo `_), which can be used to hide the page-internal table of content. -See `Hiding Contents sidebar`_. - -Change log -~~~~~~~~~~ - -See the `change log `_ for a list of relevant changes to the starter pack. - -Work with your documentation ----------------------------- - -This section is for documentation contributors. It assumes that the current -repository has been initialised with the starter pack as described in -section `Enable the starter pack`_. - -There are make targets defined in the ``Makefile`` that do various things. To -get started, we will: - -* install prerequisite software -* view the documentation - -Install prerequisite software -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before you start, make sure you have ``make`` and ``python3`` on your system: - -.. code-block:: none - - sudo apt update - sudo apt install make python3 - -Some `validation tools <#local-checks>`_ won't be available by default; -to install them, you need ``snap`` and ``npm``: - -.. code-block:: none - - sudo apt install npm snapd - -To install the core prerequisites: - -.. code-block:: none - - make install - -This will create the required software list (``.sphinx/requirements.txt``), -which is used to create a virtual environment (``.sphinx/venv``) and install -dependency software within it. - -To install the validation tools: - -.. code-block:: none - - make woke-install - make pa11y-install - -You can add further Python modules to the required software list -(``.sphinx/requirements.txt``) in the ``custom_required_modules`` variable -in the ``custom_conf.py`` file. - -**Note**: -By default, the starter pack uses the latest compatible version of all tools and does not pin its requirements. -This might change temporarily if there is an incompatibility with a new tool version. -There is therefore no need in using a tool like Renovate to automatically update the requirements. - -View the documentation -~~~~~~~~~~~~~~~~~~~~~~ - -To view the documentation: - -.. code-block:: none - - make run - -This will do several things: - -* activate the virtual environment -* build the documentation -* serve the documentation on **127.0.0.1:8000** -* rebuild the documentation each time a file is saved -* send a reload page signal to the browser when the documentation is rebuilt - -The ``run`` target is therefore very convenient when preparing to submit a -change to the documentation. - -.. note:: - - If you encounter the error ``locale.Error: unsupported locale setting`` when activating the Python virtual environment, include the environment variable in the command and try again: ``LC_ALL=en_US.UTF-8 make run`` - -Local checks -~~~~~~~~~~~~ - -Before committing and pushing changes, it's a good practice to run various checks locally to catch issues early in the development process. - -Local build -^^^^^^^^^^^ - -Run a clean build of the docs to surface any build errors that would occur in RTD: - -.. code-block:: none - - make clean-doc - make html - -Spelling check -^^^^^^^^^^^^^^ - -Ensure there are no spelling errors in the documentation: - -.. code-block:: shell - - make spelling - -Inclusive language check -^^^^^^^^^^^^^^^^^^^^^^^^ - -Ensure the documentation uses inclusive language: - -.. code-block:: shell - - make woke - -Accessibility check -^^^^^^^^^^^^^^^^^^^ - -Look for accessibility issues in rendered documentation: - -.. code-block:: shell - - make pa11y - -Link check -^^^^^^^^^^ - -Validate links within the documentation: - -.. code-block:: shell - - make linkcheck - -Configure the spelling check -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The spelling check uses ``aspell``. -Its configuration is located in the ``.sphinx/spellingcheck.yaml`` file. - -To add exceptions for words flagged by the spelling check, edit the ``.custom_wordlist.txt`` file. -You shouldn't edit ``.wordlist.txt``, because this file is maintained and updated centrally and contains words that apply across all projects. - -Configure the inclusive language check -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, the inclusive language check is applied only to reST files located -under the documentation directory (usually ``docs``). To check Markdown files, -for example, or to use a location other than the ``docs`` sub-tree, you must -change how the ``woke`` tool is invoked from within ``docs/Makefile`` (see -the `woke User Guide `_ for help). - -Inclusive language check exemptions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Some circumstances may require you to use some non-inclusive words. In such -cases you will need to create check-exemptions for them. - -This page provides an overview of two inclusive language check exemption -methods for files written in reST format. See the `woke documentation`_ for -full coverage. - -Exempt a word -............. - -To exempt an individual word, place a custom ``none`` role (defined in the -``canonical-sphinx-extensions`` Sphinx extension) anywhere on the line -containing the word in question. The role syntax is: - -.. code-block:: none - - :none:`wokeignore:rule=,` - -For instance: - -.. code-block:: none - - This is your text. The word in question is here: whitelist. More text. :none:`wokeignore:rule=whitelist,` - -To exempt an element of a URL, it is recommended to use the standard reST -method of placing links at the bottom of the page (or in a separate file). In -this case, a comment line is placed immediately above the URL line. The comment -syntax is: - -.. code-block:: none - - .. wokeignore:rule= - -Here is an example where a URL element contains the string "master": :none:`wokeignore:rule=master,` - -.. code-block:: none - - .. LINKS - .. wokeignore:rule=master - .. _link definition: https://some-external-site.io/master/some-page.html - -You can now refer to the label ``link definition_`` in the body of the text. - -Exempt an entire file -..................... - -A more drastic solution is to make an exemption for the contents of an entire -file. For example, to exempt file ``docs/foo/bar.rst`` add the following line -to file ``.wokeignore``: - -.. code-block:: none - - foo/bar.rst - -Configure the accessibility check -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``pa11y.json`` file at the starter pack root provides basic defaults; to -browse the available settings and options, see ``pa11y``'s `README -`_ on GitHub. - - -Configure the link check -~~~~~~~~~~~~~~~~~~~~~~~~ - -If you have links in the documentation that you don't want to be checked (for -example, because they are local links or give random errors even though they -work), you can add them to the ``linkcheck_ignore`` variable in the ``custom_conf.py`` file. - -Add redirects -~~~~~~~~~~~~~ - -You can add redirects to make sure existing links and bookmarks continue working when you move files around. -To do so, specify the old and new paths in the ``redirects`` setting of the ``custom_conf.py`` file. - -Other resources -~~~~~~~~~~~~~~~ - -- `Example product documentation `_ -- `Example product documentation repository `_ - -.. LINKS - -.. wokeignore:rule=master -.. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html -.. wokeignore:rule=master -.. _`Sphinx extensions`: https://www.sphinx-doc.org/en/master/usage/extensions/index.html -.. wokeignore:rule=master -.. _`file-wide metadata`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html -.. _`Furo documentation`: https://pradyunsg.me/furo/quickstart/ -.. _`Hiding Contents sidebar`: https://pradyunsg.me/furo/customisation/toc/ -.. _`Sphinx`: https://www.sphinx-doc.org/ - -.. |http://127.0.0.1:8000| replace:: ``http://127.0.0.1:8000`` -.. _`http://127.0.0.1:8000`: http://127.0.0.1:8000 -.. |sphinx-design| replace:: ``sphinx-design`` -.. _sphinx-design: https://sphinx-design.readthedocs.io/en/latest/ -.. |sphinx_tabs.tabs| replace:: ``sphinx_tabs.tabs`` -.. _sphinx_tabs.tabs: https://sphinx-tabs.readthedocs.io/en/latest/ -.. |sphinx_reredirects| replace:: ``sphinx_reredirects`` -.. _sphinx_reredirects: https://documatt.gitlab.io/sphinx-reredirects/ -.. |lxd-sphinx-extensions| replace:: ``lxd-sphinx-extensions`` -.. _lxd-sphinx-extensions: https://github.com/canonical/lxd-sphinx-extensions#lxd-sphinx-extensions -.. |sphinx_copybutton| replace:: ``sphinx_copybutton`` -.. _sphinx_copybutton: https://sphinx-copybutton.readthedocs.io/en/latest/ -.. |sphinxext.opengraph| replace:: ``sphinxext.opengraph`` -.. _sphinxext.opengraph: https://sphinxext-opengraph.readthedocs.io/en/latest/ -.. |myst_parser| replace:: ``myst_parser`` -.. _myst_parser: https://myst-parser.readthedocs.io/en/latest/ -.. |sphinxcontrib.jquery| replace:: ``sphinxcontrib.jquery`` -.. _sphinxcontrib.jquery: https://github.com/sphinx-contrib/jquery/ -.. |notfound.extension| replace:: ``notfound.extension`` -.. _notfound.extension: https://sphinx-notfound-page.readthedocs.io/en/latest/ - -.. _woke documentation: https://docs.getwoke.tech/ignore From 5d66468e1bb451324c3eb304221ca7c419bff301 Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Fri, 24 May 2024 12:01:06 +0800 Subject: [PATCH 08/14] chore: remove unnecessary files from the starter pack --- .github/workflows/automatic-doc-checks.yml | 16 ---- .wokeignore | 1 - docs/.wokeignore | 4 - docs/Makefile | 27 ------ docs/Makefile.sp | 96 ---------------------- docs/index.rst | 20 ----- 6 files changed, 164 deletions(-) delete mode 100644 .github/workflows/automatic-doc-checks.yml delete mode 120000 .wokeignore delete mode 100644 docs/.wokeignore delete mode 100644 docs/Makefile delete mode 100644 docs/Makefile.sp delete mode 100644 docs/index.rst diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml deleted file mode 100644 index cba712e5a..000000000 --- a/.github/workflows/automatic-doc-checks.yml +++ /dev/null @@ -1,16 +0,0 @@ -name: Main Documentation Checks - -on: - - push - - pull_request - - workflow_dispatch - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -jobs: - documentation-checks: - uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main - with: - working-directory: 'docs' diff --git a/.wokeignore b/.wokeignore deleted file mode 120000 index 19f3fe4bd..000000000 --- a/.wokeignore +++ /dev/null @@ -1 +0,0 @@ -docs/.wokeignore \ No newline at end of file diff --git a/docs/.wokeignore b/docs/.wokeignore deleted file mode 100644 index c64a60376..000000000 --- a/docs/.wokeignore +++ /dev/null @@ -1,4 +0,0 @@ -# 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* diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 5138e061e..000000000 --- a/docs/Makefile +++ /dev/null @@ -1,27 +0,0 @@ -# This Makefile stub allows you to customize starter pack (SP) targets. -# Consider this file as a bridge between your project -# and the starter pack's predefined targets that reside in Makefile.sp. -# -# You can add your own, non-SP targets here or override SP targets -# to fit your project's needs. For example, you can define and use targets -# named "install" or "run", but continue to use SP targets like "sp-install" -# or "sp-run" when working on the documentation. - -# Put it first so that "make" without argument is like "make help". -help: - @echo "\n" \ - "------------------------------------------------------------- \n" \ - "* watch, build and serve the documentation: make run \n" \ - "* only build: make html \n" \ - "* only serve: make serve \n" \ - "* clean built doc files: make clean-doc \n" \ - "* clean full environment: make clean \n" \ - "* check links: make linkcheck \n" \ - "* check spelling: make spelling \n" \ - "* check inclusive language: make woke \n" \ - "* check accessibility: make pa11y \n" \ - "* other possible targets: make \n" \ - "------------------------------------------------------------- \n" - -%: - $(MAKE) -f Makefile.sp sp-$@ diff --git a/docs/Makefile.sp b/docs/Makefile.sp deleted file mode 100644 index b85f6b43f..000000000 --- a/docs/Makefile.sp +++ /dev/null @@ -1,96 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXDIR = .sphinx -SPHINXOPTS ?= -c . -d $(SPHINXDIR)/.doctrees -SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build -VENVDIR = $(SPHINXDIR)/venv -PA11Y = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json -VENV = $(VENVDIR)/bin/activate - -.PHONY: sp-full-help sp-woke-install sp-pa11y-install sp-install sp-run sp-html \ - sp-epub sp-serve sp-clean sp-clean-doc sp-spelling sp-linkcheck sp-woke \ - sp-pa11y Makefile.sp - -sp-full-help: $(VENVDIR) - @. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - @echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m" - @echo "Run 'make help' to see supported targets." - -# Shouldn't assume that venv is available on Ubuntu by default; discussion here: -# https://bugs.launchpad.net/ubuntu/+source/python3.4/+bug/1290847 -$(SPHINXDIR)/requirements.txt: - python3 $(SPHINXDIR)/build_requirements.py - python3 -c "import venv" || sudo apt install python3-venv - -# If requirements are updated, venv should be rebuilt and timestamped. -$(VENVDIR): $(SPHINXDIR)/requirements.txt - @echo "... setting up virtualenv" - python3 -m venv $(VENVDIR) - . $(VENV); pip install --require-virtualenv \ - --upgrade -r $(SPHINXDIR)/requirements.txt \ - --log $(VENVDIR)/pip_install.log - @test ! -f $(VENVDIR)/pip_list.txt || \ - mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak - @. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt - @touch $(VENVDIR) - -sp-woke-install: - @type woke >/dev/null 2>&1 || \ - { echo "Installing \"woke\" snap... \n"; sudo snap install woke; } - -sp-pa11y-install: - @type $(PA11Y) >/dev/null 2>&1 || { \ - echo "Installing \"pa11y\" from npm... \n"; \ - mkdir -p $(SPHINXDIR)/node_modules/ ; \ - npm install --prefix $(SPHINXDIR) pa11y; \ - } - -sp-install: $(VENVDIR) - sudo apt-get update - sudo apt-get install --assume-yes distro-info - -sp-run: sp-install - . $(VENV); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) - -# Doesn't depend on $(BUILDDIR) to rebuild properly at every run. -sp-html: sp-install - . $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) - -sp-epub: sp-install - . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) - -sp-serve: sp-html - cd "$(BUILDDIR)"; python3 -m http.server 8000 - -sp-clean: sp-clean-doc - @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)" - rm -rf $(VENVDIR) - rm -f $(SPHINXDIR)/requirements.txt - rm -rf $(SPHINXDIR)/node_modules/ - -sp-clean-doc: - git clean -fx "$(BUILDDIR)" - rm -rf $(SPHINXDIR)/.doctrees - -sp-spelling: sp-html - . $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc) - -sp-linkcheck: sp-install - . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) - -sp-woke: sp-woke-install - woke *.rst **/*.rst --exit-1-on-failure \ - -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml - -sp-pa11y: sp-pa11y-install sp-html - find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y) - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile.sp - . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 317591c5f..000000000 --- a/docs/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -Starter pack -============ - -This starter pack contains the files you need to quickly set up your Sphinx documentation. - -Before you start, see the information about `Read the Docs at Canonical`_ and the instructions for `How to publish documentation on Read the Docs`_. - -Then, to start setting up your docs, check the :doc:`ReadMe ` for instructions. -The `Example product documentation`_ shows how to set up a Diátaxis structure in Sphinx. - -For quick help on reST or MyST syntax, see the :file:`doc-cheat-sheet.rst.txt` or :file:`doc-cheat-sheet-myst.md.txt` files in the repository. -(Open the files in your text editor; the rendered output is not very useful.) - -More information is available in the `reStructuredText style guide`_. - -.. toctree:: - :hidden: - :maxdepth: 2 - - ReadMe From 812d58caa5b25f5ee18d054b7ddbf071ae97e3b4 Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Fri, 24 May 2024 12:01:30 +0800 Subject: [PATCH 09/14] docs: using tox --- .gitignore | 2 +- docs/.gitignore | 1 - docs/.sphinx/requirements.txt | 21 +++++++++++++++++++++ docs/tox.ini | 19 +++++++++++++++++++ 4 files changed, 41 insertions(+), 2 deletions(-) create mode 100644 docs/.sphinx/requirements.txt create mode 100644 docs/tox.ini diff --git a/.gitignore b/.gitignore index a72a28d93..b6b5efe59 100644 --- a/.gitignore +++ b/.gitignore @@ -7,5 +7,5 @@ cmd/VERSION .idea .vscode /pebble - +.tox/ dist/ diff --git a/docs/.gitignore b/docs/.gitignore index 374ab3157..89b3d89ac 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,6 +1,5 @@ /*env*/ .sphinx/venv/ -.sphinx/requirements.txt .sphinx/warnings.txt .sphinx/.wordlist.dic .sphinx/.doctrees/ diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt new file mode 100644 index 000000000..400f2b841 --- /dev/null +++ b/docs/.sphinx/requirements.txt @@ -0,0 +1,21 @@ +# DO NOT MODIFY THIS FILE DIRECTLY! +# +# This file is generated automatically. +# Add custom requirements to the custom_required_modules +# array in the custom_conf.py file and run: +# make clean && make install +GitPython +canonical-sphinx-extensions +furo +linkify-it-py +myst-parser +pyspelling +sphinx +sphinx-autobuild +sphinx-copybutton +sphinx-design +sphinx-notfound-page +sphinx-tabs +sphinxcontrib-jquery +sphinxext-opengraph +watchfiles diff --git a/docs/tox.ini b/docs/tox.ini new file mode 100644 index 000000000..66bfbe1f2 --- /dev/null +++ b/docs/tox.ini @@ -0,0 +1,19 @@ +# Copyright 2024 Canonical Ltd. +# See LICENSE file for licensing details. +[tox] +work_dir = {toxinidir}/../.tox +requires = + tox>=4 + +[testenv] +basepython = python3 +setenv = + PY_COLORS=1 + +[testenv:docs] +description = Build the Sphinx docs +deps = pip-tools +commands_pre = + pip-sync {toxinidir}/.sphinx/requirements.txt +commands = + sphinx-build -W --keep-going . _build/html From 493d06669927dd5919a71c8f43fa82318e7189ea Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Fri, 24 May 2024 12:01:41 +0800 Subject: [PATCH 10/14] docs: initial markdown index page. --- docs/index.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs/index.md diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..8141f6591 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,12 @@ +# Starter pack + +This starter pack contains the files you need to quickly set up your Sphinx documentation. + +Before you start, see the information about `Read the Docs at Canonical`_ and the instructions for `How to publish documentation on Read the Docs`_. + +Then, to start setting up your docs, check the :doc:`ReadMe ` for instructions. +The `Example product documentation`_ shows how to set up a Diátaxis structure in Sphinx. + +For quick help on reST or MyST syntax, see the :file:`doc-cheat-sheet.rst.txt` or :file:`doc-cheat-sheet-myst.md.txt` files in the repository. +(Open the files in your text editor; the rendered output is not very useful.) + From f13b317b9863cc21a55aa7da1ef2cd9ddf2ccb79 Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Mon, 27 May 2024 15:20:46 +0800 Subject: [PATCH 11/14] chore: update according to code review --- docs/.sphinx/pa11y.json | 9 --------- docs/.sphinx/requirements.txt | 2 +- docs/tox.ini | 1 + 3 files changed, 2 insertions(+), 10 deletions(-) delete mode 100644 docs/.sphinx/pa11y.json diff --git a/docs/.sphinx/pa11y.json b/docs/.sphinx/pa11y.json deleted file mode 100644 index 8df0cb9cb..000000000 --- a/docs/.sphinx/pa11y.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "chromeLaunchConfig": { - "args": [ - "--no-sandbox" - ] - }, - "reporter": "cli", - "standard": "WCAG2AA" -} \ No newline at end of file diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt index 400f2b841..168da7bb8 100644 --- a/docs/.sphinx/requirements.txt +++ b/docs/.sphinx/requirements.txt @@ -3,7 +3,7 @@ # This file is generated automatically. # Add custom requirements to the custom_required_modules # array in the custom_conf.py file and run: -# make clean && make install +# python3 .sphinx/build_requirements.py GitPython canonical-sphinx-extensions furo diff --git a/docs/tox.ini b/docs/tox.ini index 66bfbe1f2..18a25eb43 100644 --- a/docs/tox.ini +++ b/docs/tox.ini @@ -4,6 +4,7 @@ work_dir = {toxinidir}/../.tox requires = tox>=4 +envlist = docs [testenv] basepython = python3 From a7b3da4a1a67699da4f8bf18dfc963746a7298d7 Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Tue, 28 May 2024 10:11:41 +0800 Subject: [PATCH 12/14] chore: move tox into docs folder --- docs/custom_conf.py | 1 + docs/tox.ini | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/custom_conf.py b/docs/custom_conf.py index f393ea093..616a2eba5 100644 --- a/docs/custom_conf.py +++ b/docs/custom_conf.py @@ -180,6 +180,7 @@ # Add files or directories that should be excluded from processing. custom_excludes = [ 'doc-cheat-sheet*', + '.tox', ] # Add CSS files (located in .sphinx/_static/) diff --git a/docs/tox.ini b/docs/tox.ini index 18a25eb43..d4dc6bf55 100644 --- a/docs/tox.ini +++ b/docs/tox.ini @@ -1,7 +1,6 @@ # Copyright 2024 Canonical Ltd. # See LICENSE file for licensing details. [tox] -work_dir = {toxinidir}/../.tox requires = tox>=4 envlist = docs From 8e25fd0823a658a7de16f7d84859e9b1dfad9a9f Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Tue, 28 May 2024 11:28:58 +0800 Subject: [PATCH 13/14] chore: fix requirements issues --- docs/requirements.txt | 164 ++++++++++++++++++++++++++++++++++++++++++ docs/tox.ini | 8 ++- 2 files changed, 171 insertions(+), 1 deletion(-) create mode 100644 docs/requirements.txt diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..61c7811c8 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,164 @@ +# +# This file is autogenerated by pip-compile with Python 3.11 +# by the following command: +# +# pip-compile --output-file=requirements.txt --strip-extras .sphinx/requirements.txt +# +alabaster==0.7.16 + # via sphinx +anyio==4.4.0 + # via + # starlette + # watchfiles +babel==2.15.0 + # via sphinx +beautifulsoup4==4.12.3 + # via + # canonical-sphinx-extensions + # furo + # pyspelling +bracex==2.4 + # via wcmatch +canonical-sphinx-extensions==0.0.21 + # via -r .sphinx/requirements.txt +certifi==2024.2.2 + # via requests +charset-normalizer==3.3.2 + # via requests +click==8.1.7 + # via uvicorn +colorama==0.4.6 + # via sphinx-autobuild +docutils==0.21.2 + # via + # canonical-sphinx-extensions + # myst-parser + # sphinx + # sphinx-tabs +furo==2024.5.6 + # via -r .sphinx/requirements.txt +gitdb==4.0.11 + # via gitpython +gitpython==3.1.43 + # via -r .sphinx/requirements.txt +h11==0.14.0 + # via uvicorn +html5lib==1.1 + # via pyspelling +idna==3.7 + # via + # anyio + # requests +imagesize==1.4.1 + # via sphinx +jinja2==3.1.4 + # via + # myst-parser + # sphinx +linkify-it-py==2.0.3 + # via -r .sphinx/requirements.txt +lxml==5.2.2 + # via pyspelling +markdown==3.6 + # via pyspelling +markdown-it-py==3.0.0 + # via + # mdit-py-plugins + # myst-parser +markupsafe==2.1.5 + # via jinja2 +mdit-py-plugins==0.4.1 + # via myst-parser +mdurl==0.1.2 + # via markdown-it-py +myst-parser==3.0.1 + # via -r .sphinx/requirements.txt +packaging==24.0 + # via sphinx +pygments==2.18.0 + # via + # furo + # sphinx + # sphinx-tabs +pyspelling==2.10 + # via -r .sphinx/requirements.txt +pyyaml==6.0.1 + # via + # myst-parser + # pyspelling +requests==2.32.2 + # via + # canonical-sphinx-extensions + # sphinx +six==1.16.0 + # via html5lib +smmap==5.0.1 + # via gitdb +sniffio==1.3.1 + # via anyio +snowballstemmer==2.2.0 + # via sphinx +soupsieve==2.5 + # via + # beautifulsoup4 + # pyspelling +sphinx==7.3.7 + # via + # -r .sphinx/requirements.txt + # canonical-sphinx-extensions + # furo + # myst-parser + # sphinx-autobuild + # sphinx-basic-ng + # sphinx-copybutton + # sphinx-design + # sphinx-notfound-page + # sphinx-tabs + # sphinxcontrib-jquery + # sphinxext-opengraph +sphinx-autobuild==2024.4.16 + # via -r .sphinx/requirements.txt +sphinx-basic-ng==1.0.0b2 + # via furo +sphinx-copybutton==0.5.2 + # via -r .sphinx/requirements.txt +sphinx-design==0.6.0 + # via -r .sphinx/requirements.txt +sphinx-notfound-page==1.0.2 + # via -r .sphinx/requirements.txt +sphinx-tabs==3.4.5 + # via -r .sphinx/requirements.txt +sphinxcontrib-applehelp==1.0.8 + # via sphinx +sphinxcontrib-devhelp==1.0.6 + # via sphinx +sphinxcontrib-htmlhelp==2.0.5 + # via sphinx +sphinxcontrib-jquery==4.1 + # via -r .sphinx/requirements.txt +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==1.0.7 + # via sphinx +sphinxcontrib-serializinghtml==1.1.10 + # via sphinx +sphinxext-opengraph==0.9.1 + # via -r .sphinx/requirements.txt +starlette==0.37.2 + # via sphinx-autobuild +uc-micro-py==1.0.3 + # via linkify-it-py +urllib3==2.2.1 + # via requests +uvicorn==0.29.0 + # via sphinx-autobuild +watchfiles==0.22.0 + # via + # -r .sphinx/requirements.txt + # sphinx-autobuild +wcmatch==8.5.2 + # via pyspelling +webencodings==0.5.1 + # via html5lib +websockets==12.0 + # via sphinx-autobuild diff --git a/docs/tox.ini b/docs/tox.ini index d4dc6bf55..5a143f6cb 100644 --- a/docs/tox.ini +++ b/docs/tox.ini @@ -10,10 +10,16 @@ basepython = python3 setenv = PY_COLORS=1 +[testenv:docs-dep] +description = Build the Sphinx docs +deps = pip-tools +commands = + pip-compile -q --strip-extras -o requirements.txt .sphinx/requirements.txt + [testenv:docs] description = Build the Sphinx docs deps = pip-tools commands_pre = - pip-sync {toxinidir}/.sphinx/requirements.txt + pip-sync {toxinidir}/requirements.txt commands = sphinx-build -W --keep-going . _build/html From 13a74b8c674df7a7fa88f3ca8997b52cd07c580c Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Tue, 28 May 2024 11:29:38 +0800 Subject: [PATCH 14/14] docs: add a paragraph about building pebble docs --- HACKING.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/HACKING.md b/HACKING.md index 5bbae7a75..c421d9051 100644 --- a/HACKING.md +++ b/HACKING.md @@ -202,6 +202,22 @@ ok github.com/canonical/pebble/cmd/pebble 0.165s ... ``` +## Docs + +We use [`sphinx`](https://www.sphinx-doc.org/en/master/) to build the docs with styles preconfigured by the [Canonical Documentation Starter Pack](https://github.com/canonical/sphinx-docs-starter-pack). + +### Building the Docs + +To build the docs, run `tox` under the `docs/` folder. + +### Pulling in the Latest Style Changes and Dependencies + +To pull in the latest style and dependencies from the starter pack, clone the [Canonical Documentation Starter Pack repository](https://github.com/canonical/sphinx-docs-starter-pack), and follow the README there. TL;DR: + +- Copy the content into the `docs/` folder. +- Remove unnecessary files (like Makefile, cheat sheets, etc.) +- Under the `docs/` folder, run `python3 build_requirements.py`. This generates the latest `requirements.txt` under the `.sphinx/` folder. +- Under the `docs/` folder, run `tox -e docs-dep` to compile a pinned requirements file for tox environments. ## Creating a release