diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml new file mode 100644 index 0000000..9e20ff6 --- /dev/null +++ b/.github/workflows/automatic-doc-checks.yml @@ -0,0 +1,19 @@ +name: Main Documentation Checks + +on: + push: + branches: [main] + pull_request: + # Manual trigger + 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" + fetch-depth: 0 diff --git a/.github/workflows/markdown-style-checks.yml b/.github/workflows/markdown-style-checks.yml new file mode 100644 index 0000000..14de967 --- /dev/null +++ b/.github/workflows/markdown-style-checks.yml @@ -0,0 +1,21 @@ +name: "Linter for Markdown" + +on: + push: + branches: + - main + pull_request: + branches: + - '*' + +jobs: + markdown-lint: + runs-on: ubuntu-22.04 + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: DavidAnson/markdownlint-cli2-action@v16 + with: + config: "docs/.sphinx/.markdownlint.json" + diff --git a/.github/workflows/periodic-style-checks.yml b/.github/workflows/periodic-style-checks.yml new file mode 100644 index 0000000..55c993b --- /dev/null +++ b/.github/workflows/periodic-style-checks.yml @@ -0,0 +1,19 @@ +name: Periodic Style Checks + +on: + schedule: + - cron: "0 1 * * 4" # Runs at 01:00 AM on every Wednesday + +jobs: + vale: + name: Style checker + runs-on: ubuntu-22.04 + defaults: + run: + shell: bash + working-directory: "sp-docs" + steps: + - uses: actions/checkout@v4 + - name: Run vale + run: | + make vale diff --git a/.github/workflows/sphinx-python-dependency-build-checks.yml b/.github/workflows/sphinx-python-dependency-build-checks.yml new file mode 100644 index 0000000..8a7d3c6 --- /dev/null +++ b/.github/workflows/sphinx-python-dependency-build-checks.yml @@ -0,0 +1,48 @@ +# The purpose of this workflow file is to confirm that the Sphinx +# virtual environment can be built from source, consequently documenting +# the packages required in the build environment to do that. +# +# This is needed because some projects embeds the documentation into built +# artifacts which involves rendering the documentation on the target +# architecture. +# +# Depending on the architecture, pip may or may not have already built wheels +# available, and as such we need to make sure building wheels from source can +# succeed. +name: Check and document build requirements for Sphinx venv +on: + - push + - pull_request + - workflow_dispatch + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + build: + name: build + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install dependencies + run: | + set -ex + sudo apt -y install \ + cargo \ + libpython3-dev \ + libxml2-dev \ + libxslt1-dev \ + make \ + python3-venv \ + rustc + - name: Build Sphinx venv + working-directory: "docs" + run: | + set -ex + make -f Makefile.sp \ + sp-install \ + PIPOPTS="--no-binary :all:" \ + || ( cat .sphinx/venv/pip_install.log && exit 1 ) diff --git a/.gitignore b/.gitignore index d00f5bd..8d9e69b 100644 --- a/.gitignore +++ b/.gitignore @@ -162,3 +162,4 @@ cython_debug/ *.charm *.rock !examples/**/lib + diff --git a/.licenserc.yaml b/.licenserc.yaml index 42efa2c..0992c0e 100644 --- a/.licenserc.yaml +++ b/.licenserc.yaml @@ -10,6 +10,7 @@ header: paths-ignore: - '.github/**' - '.woke.yaml' + - '.wokeignore' - '**/*.sum' - '**/*.json' - '**/*.j2' @@ -33,4 +34,5 @@ header: - 'examples/django/charm/lib/charms/redis_k8s/v0/redis.py' - 'examples/flask/lib/charms/redis_k8s/v0/redis.py' - 'examples/go/charm/lib/charms/redis_k8s/v0/redis.py' + - 'docs/**' comment: on-failure diff --git a/.wokeignore b/.wokeignore new file mode 120000 index 0000000..19f3fe4 --- /dev/null +++ b/.wokeignore @@ -0,0 +1 @@ +docs/.wokeignore \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 15a61af..fe341c4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,3 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] + +## 2024-11-29 + +### Changes + +Added a `docs` folder to hold the +[Canonical Sphinx starter pack](https://github.com/canonical/sphinx-docs-starter-pack) +and to eventually publish the docs on Read the Docs. diff --git a/README.md b/README.md index 3eec37d..60a615e 100644 --- a/README.md +++ b/README.md @@ -57,10 +57,12 @@ Read the for more! Additional resources: + * [Tutorial to build a rock for a Flask application](https://documentation.ubuntu.com/rockcraft/en/latest/tutorial/flask/) * [Charmcraft `flask-framework` reference](https://juju.is/docs/sdk/charmcraft-extension-flask-framework) * [Charmcraft `flask-framework` how to guides](https://juju.is/docs/sdk/build-a-paas-charm) -* [Rockcraft `flask-framework` reference](https://documentation.ubuntu.com/rockcraft/en/latest/reference/extensions/flask-framework/) +* [Rockcraft`flask-framework` + reference](https://documentation.ubuntu.com/rockcraft/en/latest/reference/extensions/flask-framework/) ## Contributing @@ -76,15 +78,19 @@ through below. 1. Please write a proposal on the [charm topic on discourse](https://discourse.charmhub.io/c/charm/41). This should cover things like: + * The integration you intend add * For each of the frameworks that PaaS Charm supports: + - The commonly used package(s) to make use of the integration - The environment variables, configuration etc. that would be made available to the app - An example for how to use the integration within an app + * The proposed implementation in `paas-app`. Take a look at [`charm.py`](paas_charm/_gunicorn/charm.py) for `gunicorn` based frameworks for integration examples. + 1. Update the [reference](https://juju.is/docs/sdk/charmcraft-extension-flask-framework) with the new integration @@ -101,6 +107,7 @@ below. 1. Please write a proposal on the [charm topic on discourse](https://discourse.charmhub.io/c/charm/41). This should cover things like: + * The programming language and framework you are thinking of * Create an example `rockcraft.yaml` file and build a working OCI image. To see an example for `flask`, install Rockcraft and run @@ -115,6 +122,7 @@ below. * The requirements and conventions for how users need to configure their app to work with PaaS Charm * Which web server to use + 1. Raise a pull request to [rockcraft](https://github.com/canonical/rockcraft) adding a new extension and profile for the framework. This is the flask [profile](https://github.com/canonical/rockcraft/blob/fdd2dee18c81b12f25e6624a5a48f9f1ac9fdb90/rockcraft/commands/init.py#L79) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt new file mode 100644 index 0000000..1b2012c --- /dev/null +++ b/docs/.custom_wordlist.txt @@ -0,0 +1,2 @@ +Charmcraft +Rockcraft diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..25893b2 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,17 @@ + +# Starter pack rules start here +/*env*/ +.sphinx/venv/ +.sphinx/warnings.txt +.sphinx/.wordlist.dic +.sphinx/.doctrees/ +.sphinx/node_modules/ +package*.json +_build +.DS_Store +__pycache__ +.idea/ +.vscode/ +.sphinx/styles/* +.sphinx/vale.ini +sp-docs/_build diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml new file mode 100644 index 0000000..b5ca6d4 --- /dev/null +++ b/docs/.readthedocs.yaml @@ -0,0 +1,33 @@ +# Copyright 2024 Canonical Ltd. +# See LICENSE file for licensing details. + +# .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-24.04 + tools: + python: "3.13" + jobs: + pre_install: + - git fetch --unshallow || true + +# Build documentation in the docs/ directory with Sphinx +sphinx: + builder: dirhtml + configuration: docs/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: docs/.sphinx/requirements.txt diff --git a/docs/.sphinx/.markdownlint.json b/docs/.sphinx/.markdownlint.json new file mode 100644 index 0000000..69ae141 --- /dev/null +++ b/docs/.sphinx/.markdownlint.json @@ -0,0 +1,16 @@ +{ + "default": false, + "MD003": { "style": "atx" }, + "MD013": { "code_blocks": false, "tables": false, "stern": true, "line_length": 120}, + "MD014": true, + "MD018": true, + "MD022": true, + "MD023": true, + "MD026": { "punctuation": ".,;。，；"}, + "MD031": { "list_items": false}, + "MD032": true, + "MD035": true, + "MD042": true, + "MD045": true, + "MD052": true +} diff --git a/docs/.sphinx/.wordlist.txt b/docs/.sphinx/.wordlist.txt new file mode 100644 index 0000000..be5021a --- /dev/null +++ b/docs/.sphinx/.wordlist.txt @@ -0,0 +1,64 @@ +ACME +ACME's +addons +AGPLv +API +APIs +balancer +Charmhub +CLI +DCO +Diátaxis +Dqlite +dropdown +EBS +EKS +enablement +favicon +Furo +Git +GitHub +Grafana +IAM +installable +JSON +Juju +Kubeflow +Kubernetes +Launchpad +linter +LTS +LXD +Makefile +Makefiles +Matrix +Mattermost +MicroCeph +MicroCloud +MicroOVN +MyST +namespace +namespaces +NodePort +Numbat +observability +OEM +OLM +Permalink +pre +Quickstart +ReadMe +reST +reStructuredText +roadmap +RTD +subdirectories +subfolders +subtree +TODO +Ubuntu +UI +UUID +VM +webhook +YAML diff --git a/docs/.sphinx/_static/css/pdf.css b/docs/.sphinx/_static/css/pdf.css new file mode 100644 index 0000000..a7a210d --- /dev/null +++ b/docs/.sphinx/_static/css/pdf.css @@ -0,0 +1,20 @@ +/* + * Copyright 2024 Canonical Ltd. + * See LICENSE file for licensing details. + */ + +/* Only relevant for specific PDF generation issues */ + +.rubric>.hclass2 { + display: block; + font-size: 2em; + border-radius: .5rem; + font-weight: 300; + line-height: 1.25; + margin-top: 1.75rem; + margin-right: -0.5rem; + margin-bottom: 0.5rem; + margin-left: -0.5rem; + padding-left: .5rem; + padding-right: .5rem; +} \ No newline at end of file diff --git a/docs/.sphinx/_static/favicon.png b/docs/.sphinx/_static/favicon.png new file mode 100644 index 0000000..7f175e4 Binary files /dev/null and b/docs/.sphinx/_static/favicon.png differ diff --git a/docs/.sphinx/_static/tag.png b/docs/.sphinx/_static/tag.png new file mode 100644 index 0000000..f6f6e5a Binary files /dev/null and b/docs/.sphinx/_static/tag.png differ diff --git a/docs/.sphinx/_templates/header.html b/docs/.sphinx/_templates/header.html new file mode 100644 index 0000000..c937139 --- /dev/null +++ b/docs/.sphinx/_templates/header.html @@ -0,0 +1,57 @@ + + + \ No newline at end of file diff --git a/docs/.sphinx/fonts/LICENCE.txt b/docs/.sphinx/fonts/LICENCE.txt new file mode 100644 index 0000000..ae78a8f --- /dev/null +++ b/docs/.sphinx/fonts/LICENCE.txt @@ -0,0 +1,96 @@ +------------------------------- +UBUNTU FONT LICENCE Version 1.0 +------------------------------- + +PREAMBLE +This licence allows the licensed fonts to be used, studied, modified and +redistributed freely. The fonts, including any derivative works, can be +bundled, embedded, and redistributed provided the terms of this licence +are met. The fonts and derivatives, however, cannot be released under +any other licence. The requirement for fonts to remain under this +licence does not require any document created using the fonts or their +derivatives to be published under this licence, as long as the primary +purpose of the document is not to be a vehicle for the distribution of +the fonts. + +DEFINITIONS +"Font Software" refers to the set of files released by the Copyright +Holder(s) under this licence and clearly marked as such. This may +include source files, build scripts and documentation. + +"Original Version" refers to the collection of Font Software components +as received under this licence. + +"Modified Version" refers to any derivative made by adding to, deleting, +or substituting -- in part or in whole -- any of the components of the +Original Version, by changing formats or by porting the Font Software to +a new environment. + +"Copyright Holder(s)" refers to all individuals and companies who have a +copyright ownership of the Font Software. + +"Substantially Changed" refers to Modified Versions which can be easily +identified as dissimilar to the Font Software by users of the Font +Software comparing the Original Version with the Modified Version. + +To "Propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification and with or without charging +a redistribution fee), making available to the public, and in some +countries other activities as well. + +PERMISSION & CONDITIONS +This licence does not grant any rights under trademark law and all such +rights are reserved. + +Permission is hereby granted, free of charge, to any person obtaining a +copy of the Font Software, to propagate the Font Software, subject to +the below conditions: + +1) Each copy of the Font Software must contain the above copyright +notice and this licence. These can be included either as stand-alone +text files, human-readable headers or in the appropriate machine- +readable metadata fields within text or binary files as long as those +fields can be easily viewed by the user. + +2) The font name complies with the following: +(a) The Original Version must retain its name, unmodified. +(b) Modified Versions which are Substantially Changed must be renamed to +avoid use of the name of the Original Version or similar names entirely. +(c) Modified Versions which are not Substantially Changed must be +renamed to both (i) retain the name of the Original Version and (ii) add +additional naming elements to distinguish the Modified Version from the +Original Version. The name of such Modified Versions must be the name of +the Original Version, with "derivative X" where X represents the name of +the new work, appended to that name. + +3) The name(s) of the Copyright Holder(s) and any contributor to the +Font Software shall not be used to promote, endorse or advertise any +Modified Version, except (i) as required by this licence, (ii) to +acknowledge the contribution(s) of the Copyright Holder(s) or (iii) with +their explicit written permission. + +4) The Font Software, modified or unmodified, in part or in whole, must +be distributed entirely under this licence, and must not be distributed +under any other licence. The requirement for fonts to remain under this +licence does not affect any document created using the Font Software, +except any version of the Font Software extracted from a document +created using the Font Software may only be distributed under this +licence. + +TERMINATION +This licence becomes null and void if any of the above conditions are +not met. + +DISCLAIMER +THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF +COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE +COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL +DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER +DEALINGS IN THE FONT SOFTWARE. diff --git a/docs/.sphinx/fonts/Ubuntu-B.ttf b/docs/.sphinx/fonts/Ubuntu-B.ttf new file mode 100644 index 0000000..b173da2 Binary files /dev/null and b/docs/.sphinx/fonts/Ubuntu-B.ttf differ diff --git a/docs/.sphinx/fonts/Ubuntu-R.ttf b/docs/.sphinx/fonts/Ubuntu-R.ttf new file mode 100644 index 0000000..d748728 Binary files /dev/null and b/docs/.sphinx/fonts/Ubuntu-R.ttf differ diff --git a/docs/.sphinx/fonts/Ubuntu-RI.ttf b/docs/.sphinx/fonts/Ubuntu-RI.ttf new file mode 100644 index 0000000..4f2d2bc Binary files /dev/null and b/docs/.sphinx/fonts/Ubuntu-RI.ttf differ diff --git a/docs/.sphinx/fonts/UbuntuMono-B.ttf b/docs/.sphinx/fonts/UbuntuMono-B.ttf new file mode 100644 index 0000000..7bd6665 Binary files /dev/null and b/docs/.sphinx/fonts/UbuntuMono-B.ttf differ diff --git a/docs/.sphinx/fonts/UbuntuMono-R.ttf b/docs/.sphinx/fonts/UbuntuMono-R.ttf new file mode 100644 index 0000000..fdd309d Binary files /dev/null and b/docs/.sphinx/fonts/UbuntuMono-R.ttf differ diff --git a/docs/.sphinx/fonts/UbuntuMono-RI.ttf b/docs/.sphinx/fonts/UbuntuMono-RI.ttf new file mode 100644 index 0000000..18f81a2 Binary files /dev/null and b/docs/.sphinx/fonts/UbuntuMono-RI.ttf differ diff --git a/docs/.sphinx/get_vale_conf.py b/docs/.sphinx/get_vale_conf.py new file mode 100644 index 0000000..e7a11e8 --- /dev/null +++ b/docs/.sphinx/get_vale_conf.py @@ -0,0 +1,56 @@ +# Copyright 2024 Canonical Ltd. +# See LICENSE file for licensing details. + +#! /usr/bin/env python + +import requests +import os + +DIR = os.getcwd() + + +def main(): + if os.path.exists(f"{DIR}/.sphinx/styles/Canonical"): + print("Vale directory exists") + else: + os.makedirs(f"{DIR}/.sphinx/styles/Canonical") + + url = ( + "https://api.github.com/repos/canonical/praecepta/" + + "contents/styles/Canonical" + ) + r = requests.get(url) + for item in r.json(): + download = requests.get(item["download_url"]) + file = open(".sphinx/styles/Canonical/" + item["name"], "w") + file.write(download.text) + file.close() + + if os.path.exists(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical"): + print("Vocab directory exists") + else: + os.makedirs(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical") + + url = ( + "https://api.github.com/repos/canonical/praecepta/" + + "contents/styles/config/vocabularies/Canonical" + ) + r = requests.get(url) + for item in r.json(): + download = requests.get(item["download_url"]) + file = open( + ".sphinx/styles/config/vocabularies/Canonical/" + item["name"], + "w" + ) + file.write(download.text) + file.close() + config = requests.get( + "https://raw.githubusercontent.com/canonical/praecepta/main/vale.ini" + ) + file = open(".sphinx/vale.ini", "w") + file.write(config.text) + file.close() + + +if __name__ == "__main__": + main() diff --git a/docs/.sphinx/images/Canonical-logo-4x.png b/docs/.sphinx/images/Canonical-logo-4x.png new file mode 100644 index 0000000..fd75696 Binary files /dev/null and b/docs/.sphinx/images/Canonical-logo-4x.png differ diff --git a/docs/.sphinx/images/front-page-light.pdf b/docs/.sphinx/images/front-page-light.pdf new file mode 100644 index 0000000..bb68cdf Binary files /dev/null and b/docs/.sphinx/images/front-page-light.pdf differ diff --git a/docs/.sphinx/images/normal-page-footer.pdf b/docs/.sphinx/images/normal-page-footer.pdf new file mode 100644 index 0000000..dfd73cb Binary files /dev/null and b/docs/.sphinx/images/normal-page-footer.pdf differ diff --git a/docs/.sphinx/latex_elements_template.txt b/docs/.sphinx/latex_elements_template.txt new file mode 100644 index 0000000..4e884b2 --- /dev/null +++ b/docs/.sphinx/latex_elements_template.txt @@ -0,0 +1,119 @@ +{ + 'papersize': 'a4paper', + 'pointsize': '11pt', + 'fncychap': '', + 'preamble': r''' +% \usepackage{charter} +% \usepackage[defaultsans]{lato} +% \usepackage{inconsolata} +\setmainfont[UprightFont = *-R, BoldFont = *-B, ItalicFont=*-RI, Extension = .ttf]{Ubuntu} +\setmonofont[UprightFont = *-R, BoldFont = *-B, ItalicFont=*-RI, Extension = .ttf]{UbuntuMono} +\usepackage[most]{tcolorbox} +\tcbuselibrary{breakable} +\usepackage{lastpage} +\usepackage{tabto} +\usepackage{ifthen} +\usepackage{etoolbox} +\usepackage{fancyhdr} +\usepackage{graphicx} +\usepackage{titlesec} +\usepackage{fontspec} +\usepackage{tikz} +\usepackage{changepage} +\usepackage{array} +\usepackage{tabularx} +\definecolor{yellowgreen}{RGB}{154, 205, 50} +\definecolor{title}{RGB}{76, 17, 48} +\definecolor{subtitle}{RGB}{116, 27, 71} +\definecolor{label}{RGB}{119, 41, 100} +\definecolor{copyright}{RGB}{174, 167, 159} +\makeatletter +\def\tcb@finalize@environment{% + \color{.}% hack for xelatex + \tcb@layer@dec% +} +\makeatother +\newenvironment{sphinxclassprompt}{\color{yellowgreen}\setmonofont[Color = 9ACD32, UprightFont = *-R, Extension = .ttf]{UbuntuMono}}{} +\tcbset{enhanced jigsaw, colback=black, fontupper=\color{white}} +\newtcolorbox{termbox}{use color stack, breakable, colupper=white, halign=flush left} +\newenvironment{sphinxclassterminal}{\setmonofont[Color = white, UprightFont = *-R, Extension = .ttf]{UbuntuMono}\sphinxsetup{VerbatimColor={black}}\begin{termbox}}{\end{termbox}} +\newcommand{\dimtorightedge}{% + \dimexpr\paperwidth-1in-\hoffset-\oddsidemargin\relax} +\newcommand{\dimtotop}{% + \dimexpr\height-1in-\voffset-\topmargin-\headheight-\headsep\relax} +\newtoggle{tpage} +\AtBeginEnvironment{titlepage}{\global\toggletrue{tpage}} +\fancypagestyle{plain}{ + \fancyhf{} + \fancyfoot[R]{\thepage\ of \pageref*{LastPage}} + \renewcommand{\headrulewidth}{0pt} + \renewcommand{\footrulewidth}{0pt} +} +\fancypagestyle{normal}{ + \fancyhf{} + \fancyfoot[R]{\thepage\ of \pageref*{LastPage}} + \renewcommand{\headrulewidth}{0pt} + \renewcommand{\footrulewidth}{0pt} +} +\fancypagestyle{titlepage}{% + \fancyhf{} + \fancyfoot[L]{\footnotesize \textcolor{copyright}{© 2024 Canonical Ltd. All rights reserved.}} +} +\newcommand\sphinxbackoftitlepage{\thispagestyle{titlepage}} +\titleformat{\chapter}[block]{\Huge \color{title} \bfseries\filright}{\thechapter .}{1.5ex}{} +\titlespacing{\chapter}{0pt}{0pt}{0pt} +\titleformat{\section}[block]{\huge \bfseries\filright}{\thesection .}{1.5ex}{} +\titlespacing{\section}{0pt}{0pt}{0pt} +\titleformat{\subsection}[block]{\Large \bfseries\filright}{\thesubsection .}{1.5ex}{} +\titlespacing{\subsection}{0pt}{0pt}{0pt} +\setcounter{tocdepth}{1} +\renewcommand\pagenumbering[1]{} +''', + 'sphinxsetup': 'verbatimwithframe=false, pre_border-radius=0pt, verbatimvisiblespace=\\phantom{}, verbatimcontinued=\\phantom{}', + 'extraclassoptions': 'openany,oneside', + 'maketitle': r''' +\begin{titlepage} +\begin{flushleft} + \begin{tikzpicture}[remember picture,overlay] + \node[anchor=south east, inner sep=0] at (current page.south east) { + \includegraphics[width=\paperwidth, height=\paperheight]{front-page-light} + }; + \end{tikzpicture} +\end{flushleft} + +\vspace*{3cm} + +\begin{adjustwidth}{8cm}{0pt} +\begin{flushleft} + \huge \textcolor{black}{\textbf{}{\raggedright{$PROJECT}}} +\end{flushleft} +\end{adjustwidth} + +\vfill + +\begin{adjustwidth}{8cm}{0pt} +\begin{tabularx}{0.5\textwidth}{ l l } + \textcolor{lightgray}{© 2024 Canonical Ltd.} & \hspace{3cm} \\ + \textcolor{lightgray}{All rights reserved.} & \hspace{3cm} \\ + & \hspace{3cm} \\ + & \hspace{3cm} \\ + +\end{tabularx} +\end{adjustwidth} + +\end{titlepage} +\RemoveFromHook{shipout/background} +\AddToHook{shipout/background}{ + \begin{tikzpicture}[remember picture,overlay] + \node[anchor=south west, align=left, inner sep=0] at (current page.south west) { + \includegraphics[width=\paperwidth]{normal-page-footer} + }; + \end{tikzpicture} + \begin{tikzpicture}[remember picture,overlay] + \node[anchor=north east, opacity=0.5, inner sep=35] at (current page.north east) { + \includegraphics[width=4cm]{Canonical-logo-4x} + }; + \end{tikzpicture} + } +''', +} diff --git a/docs/.sphinx/metrics/build_metrics.sh b/docs/.sphinx/metrics/build_metrics.sh new file mode 100755 index 0000000..bd1ff1c --- /dev/null +++ b/docs/.sphinx/metrics/build_metrics.sh @@ -0,0 +1,15 @@ +#!/bin/bash +# shellcheck disable=all + +links=0 +images=0 + +# count number of links +links=$(find . -type d -path './.sphinx' -prune -o -name '*.html' -exec cat {} + | grep -o " \n" \ + "------------------------------------------------------------- \n" + +%: + $(MAKE) -f Makefile.sp sp-$@ diff --git a/docs/Makefile.sp b/docs/Makefile.sp new file mode 100644 index 0000000..5afc57a --- /dev/null +++ b/docs/Makefile.sp @@ -0,0 +1,170 @@ +# Minimal makefile for Sphinx documentation +# +# `Makefile.sp` is from the Sphinx starter pack and should not be +# modified. +# Add your customisation to `Makefile` instead. + +# You can set these variables from the command line, and also +# from the environment for the first two. +SOURCEDIR = . +SPHINXDIR = .sphinx +VENVDIR = $(SPHINXDIR)/venv +SPHINXOPTS ?= -c . -d $(SPHINXDIR)/.doctrees -j auto +SPHINXBUILD ?= $(VENVDIR)/bin/sphinx-build +BUILDDIR = _build +PA11Y = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json +VENV = $(VENVDIR)/bin/activate +TARGET = * +ALLFILES = *.rst **/*.rst +METRICSDIR = $(SOURCEDIR)/.sphinx/metrics +REQPDFPACKS = latexmk fonts-freefont-otf texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng +CONFIRM_SUDO ?= N + +.PHONY: sp-full-help sp-woke-install sp-spellcheck-install sp-pa11y-install sp-install sp-run sp-html \ + sp-epub sp-serve sp-clean sp-clean-doc sp-spelling sp-spellcheck sp-linkcheck sp-woke \ + sp-allmetrics sp-pa11y sp-pdf-prep-force sp-pdf-prep sp-pdf Makefile.sp sp-vale sp-bash + +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." + +# If requirements are updated, venv should be rebuilt and timestamped. +$(VENVDIR): + python3 -c "import venv" || \ + (echo "You must install python3-venv before you can build the documentation."; exit 1) + @echo "... setting up virtualenv" + python3 -m venv $(VENVDIR) + . $(VENV); pip install $(PIPOPTS) --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 system-wide \"woke\" snap..."; \ + confirm_sudo=$(CONFIRM_SUDO); \ + if [ "$$confirm_sudo" != "y" ] && [ "$$confirm_sudo" != "Y" ]; then \ + read -p "This requires sudo privileges. Proceed? [y/N]: " confirm_sudo; \ + fi; \ + if [ "$$confirm_sudo" = "y" ] || [ "$$confirm_sudo" = "Y" ]; then \ + sudo snap install woke; \ + else \ + echo "Installation cancelled."; \ + fi \ + } + +sp-spellcheck-install: + @type aspell >/dev/null 2>&1 || \ + { \ + echo "Installing system-wide \"aspell\" packages..."; \ + confirm_sudo=$(CONFIRM_SUDO); \ + if [ "$$confirm_sudo" != "y" ] && [ "$$confirm_sudo" != "Y" ]; then \ + read -p "This requires sudo privileges. Proceed? [y/N]: " confirm_sudo; \ + fi; \ + if [ "$$confirm_sudo" = "y" ] || [ "$$confirm_sudo" = "Y" ]; then \ + sudo apt-get install aspell aspell-en; \ + else \ + echo "Installation cancelled."; \ + fi \ + } + +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) + +sp-run: sp-install + . $(VENV); $(VENVDIR)/bin/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 --bind 127.0.0.1 8000 + +sp-clean: sp-clean-doc + @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)" + rm -rf $(VENVDIR) + rm -rf $(SPHINXDIR)/node_modules/ + rm -rf $(SPHINXDIR)/styles + rm -rf $(SPHINXDIR)/vale.ini + +sp-clean-doc: + git clean -fx "$(BUILDDIR)" + rm -rf $(SPHINXDIR)/.doctrees + +sp-spellcheck: sp-spellcheck-install + . $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc) + +sp-spelling: sp-html sp-spellcheck + +sp-linkcheck: sp-install + . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; } + exit 0 + +sp-woke: sp-woke-install + woke $(ALLFILES) --exit-1-on-failure \ + -c https://raw.githubusercontent.com/canonical/Inclusive-naming/main/config.yml + +sp-pa11y: sp-pa11y-install sp-html + find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y) + +sp-vale: sp-install + @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale + @. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py + @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \; + @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt + @cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt + @echo "" + @echo "Running Vale against $(TARGET). To change target set TARGET= with make command" + @echo "" + @. $(VENV); vale --config "$(SPHINXDIR)/vale.ini" --glob='*.{md,txt,rst}' $(TARGET) || true + @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt + +sp-pdf-prep: sp-install + @for packageName in $(REQPDFPACKS); do (dpkg-query -W -f='$${Status}' $$packageName 2>/dev/null | \ + grep -c "ok installed" >/dev/null && echo "Package $$packageName is installed") && continue || \ + (echo "\nPDF generation requires the installation of the following packages: $(REQPDFPACKS)" && \ + echo "" && echo "Run 'sudo make pdf-prep-force' to install these packages" && echo "" && echo \ + "Please be aware these packages will be installed to your system") && exit 1 ; done + +sp-pdf-prep-force: + apt-get update + apt-get upgrade -y + apt-get install --no-install-recommends -y $(REQPDFPACKS) \ + +sp-pdf: sp-pdf-prep + @. $(VENV); sphinx-build -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) + @rm ./$(BUILDDIR)/latex/front-page-light.pdf || true + @rm ./$(BUILDDIR)/latex/normal-page-footer.pdf || true + @find ./$(BUILDDIR)/latex -name "*.pdf" -exec mv -t ./$(BUILDDIR) {} + + @rm -r $(BUILDDIR)/latex + @echo "\nOutput can be found in ./$(BUILDDIR)\n" + +sp-allmetrics: sp-html + @echo "Recording documentation metrics..." + @echo "Checking for existence of vale..." + . $(VENV) + @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale + @. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py + @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \; + @eval '$(METRICSDIR)/source_metrics.sh $(PWD)' + @eval '$(METRICSDIR)/build_metrics.sh $(PWD) $(METRICSDIR)' + +# 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 0000000..95b53c1 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,323 @@ +# Copyright 2024 Canonical Ltd. +# See LICENSE file for licensing details. + +import datetime +import ast + +# Configuration for the Sphinx documentation builder. +# All configuration specific to your project should be done in this file. +# +# If you're new to Sphinx and don't want any advanced or custom features, +# just go through the items marked 'TODO'. +# +# A complete list of built-in Sphinx configuration values: +# https://www.sphinx-doc.org/ +# +# Our starter pack uses the custom Canonical Sphinx extension +# to keep all documentation based on it consistent and on brand: +# https://github.com/canonical/canonical-sphinx + + +####################### +# Project information # +####################### + +# Project name +# +# TODO: Update with the official name of your project or product + +project = "12-Factor app support in Charmcraft and Rockcraft" +author = "Canonical Ltd." + + +# Sidebar documentation title; best kept reasonably short +# +# TODO: To include a version number, add it here (hardcoded or automated). +# +# TODO: To disable the title, set to an empty string. + +html_title = project + " documentation" + + +# Copyright string; shown at the bottom of the page +# +# Now, the starter pack uses CC-BY-SA as the license +# and the current year as the copyright year. +# +# TODO: If your docs need another license, specify it instead of 'CC-BY-SA'. +# +# TODO: If your documentation is a part of the code repository of your project, +# it inherits the code license instead; specify it instead of 'CC-BY-SA'. +# +# NOTE: For static works, it is common to provide the first publication year. +# Another option is to provide both the first year of publication +# and the current year, especially for docs that frequently change, +# e.g. 2022–2023 (note the en-dash). +# +# A way to check a repo's creation date is to get a classic GitHub token +# with 'repo' permissions; see https://github.com/settings/tokens +# Next, use 'curl' and 'jq' to extract the date from the 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 CC-BY-SA, %s" % (datetime.date.today().year, author) + + +# Documentation website URL +# +# TODO: Update with the official URL of your docs or leave empty if unsure. +# +# NOTE: The Open Graph Protocol (OGP) enhances page display in a social graph +# and is used by social media platforms; see https://ogp.me/ + +ogp_site_url = "https://canonical-starter-pack.readthedocs-hosted.com/" + + +# Preview name of the documentation website +# +# TODO: To use a different name for the project in previews, update as needed. + +ogp_site_name = project + + +# Preview image URL +# +# TODO: To customise the preview image, update as needed. + +ogp_image = \ + "https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg" + + +# Product favicon; shown in bookmarks, browser tabs, etc. + +# TODO: To customise the favicon, uncomment and update as needed. + +# html_favicon = '.sphinx/_static/favicon.png' + + +# Dictionary of values to pass into the Sphinx context for all pages: +# https://www.sphinx-doc.org/ + +html_context = { + # Product page URL; can be different from product docs URL + # + # TODO: Change to your product website URL, + # dropping the 'https://' prefix, e.g. 'ubuntu.com/lxd'. + # + # TODO: If there's no such website, + # remove the {{ product_page }} link from the page header template + # (usually .sphinx/_templates/header.html; also, see README.rst). + "product_page": "documentation.ubuntu.com", + # Product tag image; the orange part of your logo, shown in the page header + # + # TODO: To add a tag image, uncomment and update as needed. + # 'product_tag': '_static/tag.png', + # Your Discourse instance URL + # + # TODO: Change to your Discourse instance URL or leave empty. + # + # NOTE: If set, adding ':discourse: 123' to an .rst file + # will add a link to Discourse topic 123 at the bottom of the page. + "discourse": "https://discourse.charmhub.io", + # Your Mattermost channel URL + # + # TODO: Change to your Mattermost channel URL or leave empty. + "mattermost": + "", + # Your Matrix channel URL + # + # TODO: Change to your Matrix channel URL or leave empty. + "matrix": "https://matrix.to/#/#12-factor-charms:ubuntu.com", + # Your documentation GitHub repository URL + # + # TODO: Change to your documentation GitHub repository URL or leave empty. + # + # NOTE: If set, links for viewing the documentation source files + # and creating GitHub issues are added at the bottom of each page. + "github_url": "https://github.com/canonical/paas-charm", + # Docs branch in the repo; used in links for viewing the source files + # + # TODO: To customise the branch, uncomment and update as needed. + # 'github_version': 'main', + # Docs location in the repo; used in links for viewing the source files + # + # TODO: To customise the directory, uncomment and update as needed. + "github_folder": "/docs/", + + # TODO: To enable or disable the Previous / Next buttons at the bottom of pages + # Valid options: none, prev, next, both + # "sequential_nav": "both", +} + +# Project slug; see https://meta.discourse.org/t/what-is-category-slug/87897 +# +# TODO: If your documentation is hosted on https://docs.ubuntu.com/, +# uncomment and update as needed. + +# slug = '' + + +# Template and asset locations + +html_static_path = [".sphinx/_static"] +templates_path = [".sphinx/_templates"] + + +############# +# Redirects # +############# + +# To set up redirects: https://documatt.gitlab.io/sphinx-reredirects/usage.html +# For example: 'explanation/old-name.html': '../how-to/prettify.html', + +# To set up redirects in the Read the Docs project dashboard: +# https://docs.readthedocs.io/en/stable/guides/redirects.html + +# NOTE: If undefined, set to None, or empty, +# the sphinx_reredirects extension will be disabled. + +redirects = {} + + +########################### +# Link checker exceptions # +########################### + +# A regex list of URLs that are ignored by 'make linkcheck' +# +# TODO: Remove or adjust the ACME entry after you update the contributing guide + +linkcheck_ignore = [ + "http://127.0.0.1:8000", + "https://github.com/canonical/ACME/*", + "https://matrix.to/#/#12-factor-charms:ubuntu.com" +] + + +# A regex list of URLs where anchors are ignored by 'make linkcheck' + +linkcheck_anchors_ignore_for_url = [r"https://github\.com/.*"] + + +######################## +# Configuration extras # +######################## + +# Custom MyST syntax extensions; see +# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html +# +# NOTE: By default, the following MyST extensions are enabled: +# substitution, deflist, linkify + +# myst_enable_extensions = set() + + +# Custom Sphinx extensions; see "Extensions" on +# https://www.sphinx-doc.org/ + +# NOTE: The canonical_sphinx extension is required for the starter pack. +# It automatically enables the following extensions: +# - custom-rst-roles +# - myst_parser +# - notfound.extension +# - related-links +# - sphinx_copybutton +# - sphinx_design +# - sphinx_reredirects +# - sphinx_tabs.tabs +# - sphinxcontrib.jquery +# - sphinxext.opengraph +# - terminal-output +# - youtube-links + +extensions = [ + "canonical_sphinx", + "sphinxcontrib.cairosvgconverter", + "sphinx_last_updated_by_git" +] + + +# Excludes files or directories from processing + +exclude_patterns = [ + "doc-cheat-sheet*", +] + +# Adds custom CSS files, located under 'html_static_path' + +html_css_files = [ + "css/pdf.css", +] + + +# Adds custom JavaScript files, located under 'html_static_path' + +# html_js_files = [] + + +# Specifies a reST snippet to be appended to each .rst file + +rst_epilog = """ +.. include:: /reuse/links.txt +""" + +# Feedback button at the top; enabled by default +# +# TODO: To disable the button, uncomment this. + +# disable_feedback_button = True + + +# Your manpage URL +# +# TODO: To enable manpage links, uncomment and update as needed. +# +# NOTE: If set, adding ':manpage:' to an .rst file +# adds a link to the corresponding man section at the bottom of the page. + +# manpages_url = f'https://manpages.ubuntu.com/manpages/{codename}/en/' + \ +# f'man{section}/{page}.{section}.html' + + +# Specifies a reST snippet to be prepended to each .rst file +# This defines a :center: role that centers table cell content. +# This defines a :h2: role that styles content for use with PDF generation. + +rst_prolog = """ +.. role:: center + :class: align-center +.. role:: h2 + :class: hclass2 +""" + +# Workaround for https://github.com/canonical/canonical-sphinx/issues/34 + +if "discourse_prefix" not in html_context and "discourse" in html_context: + html_context["discourse_prefix"] = html_context["discourse"] + "/t/" + +##################### +# PDF configuration # +##################### + +latex_additional_files = [ + "./.sphinx/fonts/Ubuntu-B.ttf", + "./.sphinx/fonts/Ubuntu-R.ttf", + "./.sphinx/fonts/Ubuntu-RI.ttf", + "./.sphinx/fonts/UbuntuMono-R.ttf", + "./.sphinx/fonts/UbuntuMono-RI.ttf", + "./.sphinx/fonts/UbuntuMono-B.ttf", + "./.sphinx/images/Canonical-logo-4x.png", + "./.sphinx/images/front-page-light.pdf", + "./.sphinx/images/normal-page-footer.pdf", +] + +latex_engine = "xelatex" +latex_show_pagerefs = True +latex_show_urls = "footnote" + +with open(".sphinx/latex_elements_template.txt", "rt") as file: + latex_config = file.read() + +latex_elements = ast.literal_eval(latex_config.replace("$PROJECT", project)) diff --git a/docs/doc-cheat-sheet-myst.md b/docs/doc-cheat-sheet-myst.md new file mode 100644 index 0000000..d5b0b04 --- /dev/null +++ b/docs/doc-cheat-sheet-myst.md @@ -0,0 +1,273 @@ +--- +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. + +See the [MyST style guide](https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide-myst/) for detailed information and conventions. + +Also see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/index.html) for detailed information on MyST, and the [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) for general style conventions. + +## H2 heading + +Content. + +### H3 heading + +Content. + +#### H4 heading + +Content. + +##### H5 heading + +Content. + +## 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 +``` + +Demonstrate a code block (yaml): + +```yaml +code: + - example: true +``` + +(a_section_target_myst)= +## Links + +- [Canonical website](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 + +Demonstrate different kinds of 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.md + :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 0000000..b3bf401 --- /dev/null +++ b/docs/doc-cheat-sheet.rst @@ -0,0 +1,292 @@ +.. Copyright 2024 Canonical Ltd. +.. See LICENSE file for licensing details. + +:orphan: + +.. vale off + +.. _cheat-sheet: + +ReStructuredText cheat sheet +============================ + +.. vale on + +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 +---------- + +:h2:`H2 heading without TOC entry` + +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 + +Demonstrate a code block: + +.. code:: + + code: + - example: true + +Demonstrate a code block (yaml): + +.. code:: yaml + + 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/explanation/index.rst b/docs/explanation/index.rst new file mode 100644 index 0000000..d7d9bf3 --- /dev/null +++ b/docs/explanation/index.rst @@ -0,0 +1,13 @@ +.. Copyright 2024 Canonical Ltd. +.. See LICENSE file for licensing details. + +Explanation +=========== + +The following explanations provide context and clarification +on key topics related to the use and configuration of +``paas-charm`` and 12-factor app frameworks. + +.. toctree:: + :maxdepth: 1 + diff --git a/docs/how-to/contributing.rst b/docs/how-to/contributing.rst new file mode 100644 index 0000000..7f2b7e2 --- /dev/null +++ b/docs/how-to/contributing.rst @@ -0,0 +1,240 @@ +.. Copyright 2024 Canonical Ltd. +.. See LICENSE file for licensing details. + +.. TODO: Replace all mentions of ACME with your project name +.. TODO: Update all sections containing TODOs; make sure no TODOs are left + + +How to contribute +================= + +We believe that everyone has something valuable to contribute, +whether you're a coder, a writer or a tester. +Here's how and why you can get involved: + +- **Why join us?** Work with like-minded people, develop your skills, + connect with diverse professionals, and make a difference. + +- **What do you get?** Personal growth, recognition for your contributions, + early access to new features and the joy of seeing your work appreciated. + +- **Start early, start easy**: Dive into code contributions, + improve documentation, or be among the first testers. + Your presence matters, + regardless of experience or the size of your contribution. + + +The guidelines below will help keep your contributions effective and meaningful. + + +Code of conduct +--------------- + +When contributing, you must abide by the +`Ubuntu Code of Conduct `_. + +.. TODO: Do we link the `IS Charms contributing guide `_? + +License and copyright +--------------------- + +.. TODO: Update with your license details or drop if excessive + + +Releases and versions +--------------------- + +.. TODO: Add your release and versioning details or drop if excessive + +The 12-factor project uses `semantic versioning `_; +major releases occur once or twice a year. + +The release notes can be found `here `_. + + +Environment setup +----------------- + +.. TODO: Update with your prerequisites or drop if excessive + + +Submissions +----------- + +.. TODO: Suggest your own PR process or drop if excessive + +If you want to address an issue or a bug in the 12-factor project, +notify in advance the people involved to avoid confusion; +also, reference the issue or bug number when you submit the changes. + +- `Fork + `_ + our `GitHub repository `_ + and add the changes to your fork, + properly structuring your commits, + providing detailed commit messages + and signing your commits. + +- Make sure the updated project builds and runs without warnings or errors; + this includes linting, documentation, code and tests. + +- Submit the changes as a `pull request (PR) + `_. + + +Your changes will be reviewed in due time; +if approved, they will be eventually merged. + + +Describing pull requests +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. TODO: Update with your own checklist or drop if excessive + +To be properly considered, reviewed and merged, +your pull request must provide the following details: + +- **Title**: Summarize the change in a short, descriptive title. + +- **Description**: Explain the problem that your pull request solves. + Mention any new features, bug fixes or refactoring. + +- **Relevant issues**: Reference any + `related issues, pull requests and repositories `_. + +- **Testing**: Explain whether new or updated tests are included. + +- **Reversibility**: If you propose decisions that may be costly to reverse, + list the reasons and suggest steps to reverse the changes if necessary. + + +Commit structure and messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. TODO: Update with your own guidelines or drop if excessive + +Use separate commits for each logical change, +and for changes to different components. + +Use `conventional commits `_ +to ensure consistency across the project: + +Such structure makes it easier to review contributions +and simplifies porting fixes to other branches. + + +Signing commits +~~~~~~~~~~~~~~~ + +.. TODO: Update with your suggestions or drop if excessive + +To improve contribution tracking, +we use the developer certificate of origin +(`DCO 1.1 `_) +and require a "sign-off" for any changes going into each branch. + +The sign-off is a simple line at the end of the commit message +certifying that you wrote it +or have the right to commit it as an open-source contribution. + +To sign off on a commit, use the ``--signoff`` option in ``git commit``. + + +Code +---- + +Formatting and linting +~~~~~~~~~~~~~~~~~~~~~~ + +.. TODO: Update with your linting configuration setup or drop if excessive + +Structure +~~~~~~~~~ + +- **Check linked code elements**: + Check that coupled code elements, files and directories are adjacent. + For instance, store test data close to the corresponding test code. + +- **Group variable declaration and initialization**: + Declare and initialize variables together + to improve code organization and readability. + +- **Split large expressions**: + Break down large expressions + into smaller self-explanatory parts. + Use multiple variables where appropriate + to make the code more understandable + and choose names that reflect their purpose. + +- **Use blank lines for logical separation**: + Insert a blank line between two logically separate sections of code. + This improves its structure and makes it easier to understand. + +- **Avoid nested conditions**: + Avoid nesting conditions to improve readability and maintainability. + +- **Remove dead code and redundant comments**: + Drop unused or obsolete code and comments. + This promotes a cleaner code base and reduces confusion. + +- **Normalize symmetries**: + Treat identical operations consistently, using a uniform approach. + This also improves consistency and readability. + + +Best practices +~~~~~~~~~~~~~~ + +.. TODO: Update with your best practices or drop if excessive + + +Tests +----- + +.. TODO: Update with your testing framework details or drop if excessive + +All code contributions must include tests. + +To run the tests locally before submitting your changes: + +.. code-block:: console + + TODO: test command 1 + TODO: test command 2 + + +Documentation +------------- + +The documentation is stored in the ``docs`` directory of the repository. +It is based on the `Canonical starter pack +`_ +and hosted on `Read the Docs `_. + +For syntax help and guidelines, +refer to the `Canonical style guides +`_. + +In structuring, +the documentation employs the `Diátaxis `_ approach. + +To run the documentation locally before submitting your changes: + +.. code-block:: bash + + make run + + +Automatic checks +~~~~~~~~~~~~~~~~ + +GitHub runs automatic checks on the documentation +to verify spelling, validate links and suggest inclusive language. + +You can (and should) run the same checks locally: + +.. code-block:: bash + + make spelling + make linkcheck + make woke diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst new file mode 100644 index 0000000..c7d0b4d --- /dev/null +++ b/docs/how-to/index.rst @@ -0,0 +1,12 @@ +.. Copyright 2024 Canonical Ltd. +.. See LICENSE file for licensing details. + +How-to guides +============= + +Step-by-step instructions for developing and maintaining a framework in the 12-factor app project. + +.. toctree:: + :maxdepth: 1 + + Contribute diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..5a0abac --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,68 @@ +.. Copyright 2024 Canonical Ltd. +.. See LICENSE file for licensing details. + +12-Factor app support in Charmcraft and Rockcraft +================================================= + +**Coordinated pairs of Rockcraft and Charmcraft profiles designed to give you +the content you need to generate rocks and charms for 12-Factor applications.** + +**A paragraph of one to three short sentences, that describe what the product +does.** + +**A third paragraph of similar length, this time explaining what need the +product meets.** + +**Finally, a paragraph that describes whom the product is useful for.** + +--------- + +In this documentation +--------------------- + +.. grid:: 1 1 2 2 + + .. grid-item:: :doc:`Tutorial ` + + **Start here**: a hands-on introduction to Example Product for new users + + .. grid-item:: :doc:`How-to guides ` + + **Step-by-step guides** covering key operations and common tasks + +.. grid:: 1 1 2 2 + :reverse: + + .. grid-item:: :doc:`Reference ` + + **Technical information** - specifications, APIs, architecture + + .. grid-item:: :doc:`Explanation ` + + **Discussion and clarification** of key topics + +--------- + +Project and community +--------------------- + +The 12-Factor app project is a member of the Ubuntu family. It’s an open source +project that warmly welcomes community projects, contributions, suggestions, +fixes and constructive feedback. + +* `Code of conduct `_ +* `Get support `_ +* `Join our online chat `_ +* Contribute +* Roadmap + +Thinking about using 12-Factor app rocks and charms in your next project? Get in touch! + + +.. toctree:: + :hidden: + :maxdepth: 1 + + Tutorial + How to + Explanation diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt new file mode 100644 index 0000000..f9d3d5c --- /dev/null +++ b/docs/reuse/links.txt @@ -0,0 +1 @@ +.. _link text: https://example.com diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst new file mode 100644 index 0000000..6f18154 --- /dev/null +++ b/docs/tutorial/index.rst @@ -0,0 +1,12 @@ +.. Copyright 2024 Canonical Ltd. +.. See LICENSE file for licensing details. + +Tutorials +========= + +Developer tutorials for the 12-factor app project. + +.. toctree:: + :maxdepth: 1 + +