diff --git a/docs/moonray/.custom_wordlist.txt b/docs/moonray/.custom_wordlist.txt new file mode 100644 index 000000000..e69de29bb diff --git a/docs/moonray/.gitignore b/docs/moonray/.gitignore new file mode 100644 index 000000000..149ab4937 --- /dev/null +++ b/docs/moonray/.gitignore @@ -0,0 +1,14 @@ +/*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 diff --git a/docs/moonray/.readthedocs.yaml b/docs/moonray/.readthedocs.yaml new file mode 100644 index 000000000..a3d34d2b6 --- /dev/null +++ b/docs/moonray/.readthedocs.yaml @@ -0,0 +1,30 @@ +# .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: + pre_install: + - git fetch --unshallow || true + +# Build documentation in the docs/ directory with Sphinx +sphinx: + builder: dirhtml + configuration: docs/moonray/conf.py + fail_on_warning: false + +# 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/moonray/.sphinx/requirements.txt diff --git a/docs/moonray/.sphinx/.wordlist.txt b/docs/moonray/.sphinx/.wordlist.txt new file mode 100644 index 000000000..fb4137d3b --- /dev/null +++ b/docs/moonray/.sphinx/.wordlist.txt @@ -0,0 +1,61 @@ +# This wordlist is from the Sphinx starter pack and should not be +# modified. Add any custom terms to .custom_wordlist.txt instead. + +addons +API +APIs +balancer +Charmhub +CLI +Diátaxis +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 +Ubuntu +UI +UUID +VM +webhook +YAML diff --git a/docs/moonray/.sphinx/_static/favicon.png b/docs/moonray/.sphinx/_static/favicon.png new file mode 100644 index 000000000..7f175e461 Binary files /dev/null and b/docs/moonray/.sphinx/_static/favicon.png differ diff --git a/docs/moonray/.sphinx/_static/tag.png b/docs/moonray/.sphinx/_static/tag.png new file mode 100644 index 000000000..f6f6e5aa4 Binary files /dev/null and b/docs/moonray/.sphinx/_static/tag.png differ diff --git a/docs/moonray/.sphinx/_templates/header.html b/docs/moonray/.sphinx/_templates/header.html new file mode 100644 index 000000000..1a128b6f8 --- /dev/null +++ b/docs/moonray/.sphinx/_templates/header.html @@ -0,0 +1,36 @@ + diff --git a/docs/moonray/.sphinx/get_vale_conf.py b/docs/moonray/.sphinx/get_vale_conf.py new file mode 100644 index 000000000..e95294868 --- /dev/null +++ b/docs/moonray/.sphinx/get_vale_conf.py @@ -0,0 +1,29 @@ +#! /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() + + 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/moonray/.sphinx/pa11y.json b/docs/moonray/.sphinx/pa11y.json new file mode 100644 index 000000000..04dc1e1c5 --- /dev/null +++ b/docs/moonray/.sphinx/pa11y.json @@ -0,0 +1,9 @@ +{ + "chromeLaunchConfig": { + "args": [ + "--no-sandbox" + ] + }, + "reporter": "cli", + "standard": "WCAG2AA" +} diff --git a/docs/moonray/.sphinx/requirements.txt b/docs/moonray/.sphinx/requirements.txt new file mode 100644 index 000000000..c019f178a --- /dev/null +++ b/docs/moonray/.sphinx/requirements.txt @@ -0,0 +1,2 @@ +git+https://github.com/canonical/canonical-sphinx@main#egg=canonical-sphinx +sphinx-autobuild diff --git a/docs/moonray/.sphinx/spellingcheck.yaml b/docs/moonray/.sphinx/spellingcheck.yaml new file mode 100644 index 000000000..5f3dbad35 --- /dev/null +++ b/docs/moonray/.sphinx/spellingcheck.yaml @@ -0,0 +1,30 @@ +matrix: +- name: rST files + aspell: + lang: en + d: en_GB + dictionary: + wordlists: + - .sphinx/.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/moonray/.wokeignore b/docs/moonray/.wokeignore new file mode 100644 index 000000000..c64a60376 --- /dev/null +++ b/docs/moonray/.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/moonray/Makefile b/docs/moonray/Makefile new file mode 100644 index 000000000..a861ba84a --- /dev/null +++ b/docs/moonray/Makefile @@ -0,0 +1,30 @@ +# 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 spelling (without building again): make spellcheck \n" \ + "* check inclusive language: make woke \n" \ + "* check accessibility: make pa11y \n" \ + "* check style guide compliance: make vale \n" \ + "* check style guide compliance on target: make vale TARGET=* \n" \ + "* other possible targets: make \n" \ + "------------------------------------------------------------- \n" + +%: + $(MAKE) -f Makefile.sp sp-$@ diff --git a/docs/moonray/Makefile.sp b/docs/moonray/Makefile.sp new file mode 100644 index 000000000..a7f4a7121 --- /dev/null +++ b/docs/moonray/Makefile.sp @@ -0,0 +1,110 @@ +# 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. +SPHINXDIR = .sphinx +SPHINXOPTS ?= -c . -d $(SPHINXDIR)/.doctrees +SPHINXBUILD ?= $(VENVDIR)/bin/sphinx-build +SOURCEDIR = . +BUILDDIR = _build +VENVDIR = $(SPHINXDIR)/venv +PA11Y = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json +VENV = $(VENVDIR)/bin/activate +TARGET = * +ALLFILES = *.rst **/*.rst + +.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-spellcheck sp-linkcheck sp-woke \ + sp-pa11y Makefile.sp sp-vale + +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 --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) + +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: + . $(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://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) + +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 \; + @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) + + + +# 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/moonray/_parts/test.md b/docs/moonray/_parts/test.md new file mode 100644 index 000000000..788be2534 --- /dev/null +++ b/docs/moonray/_parts/test.md @@ -0,0 +1,3 @@ +# Test file for inclusion + +This is a test for the {{product}} documentation set \ No newline at end of file diff --git a/docs/moonray/conf.py b/docs/moonray/conf.py new file mode 100644 index 000000000..f9836e3a3 --- /dev/null +++ b/docs/moonray/conf.py @@ -0,0 +1,227 @@ +import datetime +import os +import yaml + +# Configuration for the Sphinx documentation builder. +# All configuration specific to your project should be done in this file. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html +# For our custom configuration, see the Canonical Sphinx extension: +# https://github.com/canonical/canonical-sphinx +# +# 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 = 'Moonray' +author = 'Canonical 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 CC-BY-SA as the license and the current year +# as the copyright year. +# +# If your documentation needs a different copyright license, use that +# instead of 'CC-BY-SA'. Also, if your documentation is included as +# part of the code repository of your project, it'll inherit the license +# of the code. So you'll need to specify that license here (instead of +# 'CC-BY-SA'). +# +# 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 CC-BY-SA, %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) +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': '/docs/moonray/', + + # 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", + + # Uncomment to disable displaying the contributors for each file. + # (You can also limit the time frame for displaying contributors + # by setting a "display_contributors_since" variable.) + # "display_contributors": False, + +} + +# If your project is on documentation.ubuntu.com, specify the project +# slug (for example, "lxd") here. +# slug = "" + +# These paths are needed if you want to override any default assets. +# You can comment them out if you don't need this (but you can also just +# leave them). + +html_static_path = ['.sphinx/_static'] +templates_path = ['.sphinx/_templates'] + +############################################################ +### 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) +linkcheck_anchors_ignore_for_url = [ + r'https://github\.com/.*' +] + +############################################################ +### Additions to default configuration +############################################################ + +## The following settings are appended to the default configuration. +## Use them to extend the default functionality. + +# By default, the following MyST extensions are enabled: +# substitution, deflist, linkify +# If you need more extensions, add them here. +# myst_enable_extensions = set() + +# You must include the canonical_sphinx extension here. +# This extension automatically enables the following Sphinx extensions: +# custom-rst-roles, myst_parser, notfound.extension, related-links, +# sphinx_copybutton, sphinx_design, sphinx_tabs.tabs, +# sphinx_reredirects, sphinxcontrib.jquery, sphinxext.opengraph, +# terminal-output, youtube-links +# If you need more extensions, add them here (in addition to +# canonical_sphinx). +extensions = [ + 'canonical_sphinx' + ] + +# Add files or directories that should be excluded from processing. +exclude_patterns = [ + 'doc-cheat-sheet*', + ] + +# Add custom CSS files (located in .sphinx/_static/) +# html_css_files = [] + +# Add custom JavaScript files (located in .sphinx/_static/) +# html_js_files = [] + +## The following settings override the default configuration. + +# Specify a reST string that is included at the end of each file. +# The suggested value pulls the reuse/links.txt file into each reST file. +rst_epilog = ''' +.. include:: /reuse/links.txt +''' + +# 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 + +# If you are using the :manpage: role, set this variable to the URL for the version +# that you want to link to: +# manpages_url = "https://manpages.ubuntu.com/manpages/noble/en/man{section}/{page}.{section}.html" + +############################################################ +### 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 +''' + +############################################################ +### Myst configuration +############################################################ +if os.path.exists('./reuse/substitutions.yaml'): + with open('./reuse/substitutions.yaml', 'r') as fd: + myst_substitutions = yaml.safe_load(fd.read()) diff --git a/docs/moonray/doc-cheat-sheet-myst.md b/docs/moonray/doc-cheat-sheet-myst.md new file mode 100644 index 000000000..6257c9db0 --- /dev/null +++ b/docs/moonray/doc-cheat-sheet-myst.md @@ -0,0 +1,261 @@ +--- +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 + +### 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/) +- {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.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/moonray/doc-cheat-sheet.rst b/docs/moonray/doc-cheat-sheet.rst new file mode 100644 index 000000000..ca3fd0622 --- /dev/null +++ b/docs/moonray/doc-cheat-sheet.rst @@ -0,0 +1,285 @@ +: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 +---------- + +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/moonray/explanation/about.md b/docs/moonray/explanation/about.md new file mode 100644 index 000000000..44f93df2c --- /dev/null +++ b/docs/moonray/explanation/about.md @@ -0,0 +1,12 @@ +# What is {{product}}? + +At its core, {{product}} is a full implementation of upstream +[Kubernetes][] delivered in a compact, secure, reliable [snap][] package. As the +upstream Kubernetes services are not all that is required for a fully +functional cluster, additional services and features are built in. You can +deploy the snap and have a single-node cluster up and running in minutes. + + + +[Kubernetes]: https://kubernetes.io/ +[snap]: https://snapcraft.io/docs \ No newline at end of file diff --git a/docs/moonray/explanation/index.md b/docs/moonray/explanation/index.md new file mode 100644 index 000000000..833b6a071 --- /dev/null +++ b/docs/moonray/explanation/index.md @@ -0,0 +1,36 @@ +# Explanation + +For a better understanding of how {{product}} works and related +topics such as security, these pages will help expand your knowledge and +get the most out of Kubernetes. + +```{toctree} +:hidden: +Overview +``` + +```{toctree} +:titlesonly: +about +``` + +--- + +## Other documentation types + +If you are just getting started, the [Tutorials section] contains +step-by-step tutorials to help guide you through exploring and using +{{product}}. + +If you have a specific goal our [How-to guides] have more in-depth +detail than tutorials and can be applied to a broader set of applications. +They’ll help you achieve an end-result but may require you to understand and +adapt the steps to fit your specific requirements. + +Finally, our [Reference section] is for when you need to check specific +details or information such as the command reference or release notes. + + +[Tutorials section]: ../tutorial/index +[How-to guides]: ../howto/index +[Reference section]: ../reference/index diff --git a/docs/moonray/howto/index.md b/docs/moonray/howto/index.md new file mode 100644 index 000000000..041e13e6c --- /dev/null +++ b/docs/moonray/howto/index.md @@ -0,0 +1,40 @@ +# How-to guides + +If you have a specific goal, but are already familiar with Kubernetes, our +How-to guides are more specific and contain less background information. +They’ll help you achieve an end result but may require you to understand and +adapt the steps to fit your specific requirements. + +```{toctree} +:hidden: +Overview +``` + +```{toctree} +:glob: +:titlesonly: +install + +``` + +--- + +## Other documentation types + +Our Reference section is for when you need to check specific details or +information such as the command reference or release notes. + +Alternatively, the [Tutorials section] contains step-by-step tutorials to help +guide you through exploring and using Canonical Kubernetes. + +For a better understanding of how {{product}} works and related topics +such as security, our [Explanation section] helps you expand your knowledge +and get the most out of Kubernetes. + +Finally, our [Reference section] is for when you need to check specific details +or information such as the command reference or release notes. + + +[Tutorials section]: ../tutorial/index +[Explanation section]: ../explanation/index +[Reference section]: ../reference/index diff --git a/docs/moonray/howto/install.md b/docs/moonray/howto/install.md new file mode 100644 index 000000000..df8040541 --- /dev/null +++ b/docs/moonray/howto/install.md @@ -0,0 +1,5 @@ +```{include} ../../src/snap/howto/install/snap.md + +``` + + diff --git a/docs/moonray/index.md b/docs/moonray/index.md new file mode 100644 index 000000000..9d3278ce8 --- /dev/null +++ b/docs/moonray/index.md @@ -0,0 +1,74 @@ +# {{product}} documentation + +{{product}} is a performant, lightweight, secure and +opinionated distribution of **Kubernetes** which includes everything needed to +create and manage a scalable cluster suitable for all use cases. + +You can find out more about {{product}} on this [overview page] or +see a more detailed explanation in our [architecture documentation]. + +![Illustration depicting working on components and clouds][logo] + +```{toctree} +:hidden: +:titlesonly: +Home +tutorial/index +howto/index +explanation/index +reference/index +``` + + +--- + +## In this documentation + +````{grid} 1 1 2 2 + +```{grid-item-card} [Tutorial](tutorial/index) + +**Start here!** A hands-on introduction to {{product}} for new users +``` + +```{grid-item-card} [How-to guides](howto/index) + +**Step-by-step guides** covering key operations and common tasks +``` + +```` + +````{grid} 1 1 2 2 + + +```{grid-item-card} [Reference](reference/index) + +**Technical information** - specifications, APIs, architecture +``` + +```{grid-item-card} [Explanation](explanation/index) + +**Discussion and clarification** of key topics +``` + +```` + +--- + +## Project and community + +{{product}} is an open source project which welcomes community involvement, +contributions, suggestions, fixes and constructive feedback. + +- Our [Code of Conduct] + + + + +[logo]: https://assets.ubuntu.com/v1/843c77b6-juju-at-a-glace.svg + + + +[Code of Conduct]: https://ubuntu.com/community/ethos/code-of-conduct + + diff --git a/docs/moonray/make.bat b/docs/moonray/make.bat new file mode 100644 index 000000000..32bb24529 --- /dev/null +++ b/docs/moonray/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/moonray/reference/index.md b/docs/moonray/reference/index.md new file mode 100644 index 000000000..e6ea1a4bc --- /dev/null +++ b/docs/moonray/reference/index.md @@ -0,0 +1,34 @@ +# Reference + +Our Reference section is for when you need to check specific details or +information such as the command reference or release notes. + +```{toctree} +:hidden: +Overview +``` + +```{toctree} +:titlesonly: +test + +``` + +## Other documentation types + +Alternatively, the [Tutorials section] contains step-by-step tutorials to help +guide you through exploring and using {{product}}. + +If you have a specific goal our [How-to guides] have more in-depth detail than +tutorials and can be applied to a broader set of applications. They’ll help you +achieve an end-result but may require you to understand and adapt the steps to +fit your specific requirements. + +Finally, for a better understanding of how {{product}} works and +related topics such as security, our [Explanation section] helps you to expand +your knowledge and get the most out of Kubernetes. + + +[Tutorials section]: ../tutorial/index +[How-to guides]: ../howto/index +[Explanation section]: ../explanation/index diff --git a/docs/moonray/reference/test.md b/docs/moonray/reference/test.md new file mode 100644 index 000000000..50a9257a9 --- /dev/null +++ b/docs/moonray/reference/test.md @@ -0,0 +1,3 @@ +```{include} ../_parts/test.md + +``` \ No newline at end of file diff --git a/docs/moonray/reuse/links.txt b/docs/moonray/reuse/links.txt new file mode 100644 index 000000000..f9d3d5cdc --- /dev/null +++ b/docs/moonray/reuse/links.txt @@ -0,0 +1 @@ +.. _link text: https://example.com diff --git a/docs/moonray/reuse/substitutions.yaml b/docs/moonray/reuse/substitutions.yaml new file mode 100644 index 000000000..a0c8eeddd --- /dev/null +++ b/docs/moonray/reuse/substitutions.yaml @@ -0,0 +1,4 @@ +product: 'Moonray' +formatted_text: |- + *Multi-line* text + that uses basic **markup**. diff --git a/docs/moonray/tutorial/index.md b/docs/moonray/tutorial/index.md new file mode 100644 index 000000000..d63865e3b --- /dev/null +++ b/docs/moonray/tutorial/index.md @@ -0,0 +1,36 @@ +# Tutorials + +This section contains a step-by-step guide to help you start exploring how to +install and use {{product}}. + +```{toctree} +:hidden: +Overview +``` + +```{toctree} +:glob: +:titlesonly: + +``` + +--- + +## Other documentation types + +If you have a specific goal our [How-to guides] have more in-depth detail than +tutorials and can be applied to a broader set of applications. They’ll help you +achieve an end-result but may require you to understand and adapt the steps to +fit your specific requirements. + +For a better understanding of how {{product}} works and related topics +such as security, our [Explanation section] helps you to expand your knowledge +and get the most out of Kubernetes. + +Finally, our [Reference section] is for when you need to check specific details +or information such as the command reference or release notes. + + +[How-to guides]: ../howto/index +[Explanation section]: ../explanation/index +[Reference section]: ../reference/index