diff --git a/doc/.sphinx/requirements.txt b/doc/.sphinx/requirements.txt new file mode 100644 index 000000000..3ed17ae84 --- /dev/null +++ b/doc/.sphinx/requirements.txt @@ -0,0 +1,6 @@ +furo +m2r2 +sphinx==5.1.1 +sphinx_autobuild +sphinx_copybutton +sphinx_design diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 000000000..5f863f1d6 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,66 @@ +#Minimal makefile for Sphinx documentation + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build +VENV = .sphinx/venv/bin/activate + + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +install: + @echo "... setting up virtualenv" + python3 -m venv .sphinx/venv + . $(VENV); pip install --upgrade -r .sphinx/requirements.txt + + @echo "\n" \ + "--------------------------------------------------------------- \n" \ + "* watch, build and serve the documentation: make run \n" \ + "* only build: make html \n" \ + "* only epub: make epub \n" \ + "* only serve: make serve \n" \ + "* clean built doc files: make clean-doc \n" \ + "* clean full environment: make clean \n" \ + "* check spelling: make spelling \n" \ + "* check links: make linkcheck \n" \ + "* check inclusive language: make woke \n" \ + "--------------------------------------------------------------- \n" +run: + . $(VENV); sphinx-autobuild -c . -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" + +html: + . $(VENV); $(SPHINXBUILD) -c . -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt + +epub: + . $(VENV); $(SPHINXBUILD) -c . -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt + +serve: + cd "$(BUILDDIR)"; python3 -m http.server 8000 + +clean: clean-doc + rm -rf .sphinx/venv + +clean-doc: + git clean -fx "$(BUILDDIR)" + +spelling: html + . $(VENV) ; python3 -m pyspelling -c .sphinx/spellingcheck.yaml + +linkcheck: + . $(VENV) ; $(SPHINXBUILD) -c . -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" + +woke: + type woke >/dev/null 2>&1 || { snap install woke; exit 1; } + woke *.rst **/*.rst -c https://github.com/canonical-web-and-design/Inclusive-naming/raw/main/config.yml + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 000000000..57bf8facb --- /dev/null +++ b/doc/README.md @@ -0,0 +1,8 @@ +# Documentation + +This temporary folder (`../doc/`) is subject to change and only exists to help +migrate the official documentation for this project to readthedocs.com. + +The `../documentation/` folder is the working location for our docs. Any changes +you would like to add to the documentation should be made from this directory, +and not from `../doc/`. diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css new file mode 100644 index 000000000..eb525eb19 --- /dev/null +++ b/doc/_static/css/custom.css @@ -0,0 +1,248 @@ +/** Fix the font weight (300 for normal, 400 for slightly bold) **/ +/** Should be 100 for all headers, 400 for normal text **/ + +h1, h2, h3, h4, h5, h6, .sidebar-tree .current-page>.reference, button, input, optgroup, select, textarea, th.head { + font-weight: 200; +} + +.toc-title { + font-weight: 400; +} + +.sidebar-tree .toctree-l2.has-children>.reference { + font-weight: 300; +} + +li.toctree-l3 { + font-weight: 200; +} + +div.page, li.scroll-current>.reference, dl.glossary dt, dl.simple dt, dl:not([class]) dt { + font-weight: 300; + line-height: 1.5; + font-size: var(--font-size--normal); +} + + +/** Side bars (side-bar tree = left, toc-tree = right) **/ +div.sidebar-tree { + font-weight: 200; + line-height: 1.5; + font-size: var(--font-size--normal); +} + +div.toc-tree { + font-weight: 200; + font-size: var(--font-size--medium); + line-height: 1.5; +} + +.sidebar-tree .toctree-l1>.reference, .toc-tree li.scroll-current>.reference { + font-weight: 400; +} + +/** List styling **/ +ol, ul { + margin-bottom: 1.5rem; + margin-left: 1rem; + margin-top: 0; + padding-left: 1rem; +} + +/** Table styling **/ + +th.head { + text-transform: uppercase; + font-size: var(--font-size--small); +} + +table.docutils { + border: 0; + box-shadow: none; + width:100%; +} + +table.docutils td, table.docutils th, table.docutils td:last-child, table.docutils th:last-child, table.docutils td:first-child, table.docutils th:first-child { + border-right: none; + border-left: none; +} + +/* center align table cells with ":-:" */ +td.text-center { + text-align: center; +} + +/** No rounded corners **/ + +.admonition, code.literal, .sphinx-tabs-tab, .sphinx-tabs-panel, .highlight { + border-radius: 0; +} + +/** code blocks and literals **/ +code.docutils.literal.notranslate, .highlight pre, pre.literal-block { + font-size: var(--font-size--medium); +} + + +/** Admonition styling **/ + +.admonition { + font-size: var(--font-size--medium); + box-shadow: none; +} + +/** Styling for links **/ +/* unvisited link */ +a:link { + color: #06c; + text-decoration: none; +} + +/* visited link */ +a:visited { + color: #7d42b8; + text-decoration: none; +} + +/* mouse over link */ +a:hover { + text-decoration: underline; +} + +/* selected link */ +a:active { + text-decoration: underline; +} + +a.sidebar-brand.centered { + text-decoration: none; +} + +/** Color for the "copy link" symbol next to headings **/ + +a.headerlink { + color: var(--color-brand-primary); +} + +/** Line to the left of the current navigation entry **/ + +.sidebar-tree li.current-page { + border-left: 2px solid var(--color-brand-primary); +} + +/** Some tweaks for issue #16 **/ + +[role="tablist"] { + border-bottom: 1px solid var(--color-sidebar-item-background--hover); +} + +.sphinx-tabs-tab[aria-selected="true"] { + border: 0; + border-bottom: 2px solid var(--color-brand-primary); + background-color: var(--color-sidebar-item-background--current); + font-weight:300; +} + +.sphinx-tabs-tab{ + color: var(--color-brand-primary); + font-weight:300; +} + +.sphinx-tabs-panel { + border: 0; + border-bottom: 1px solid var(--color-sidebar-item-background--hover); + background: var(--color-background-primary); +} + +button.sphinx-tabs-tab:hover { + background-color: var(--color-sidebar-item-background--hover); +} + +/** Custom classes to fix scrolling in tables by decreasing the + font size or breaking certain columns. + Specify the classes in the Markdown file with, for example: + ```{rst-class} break-col-4 min-width-4-8 + ``` +**/ + +table.dec-font-size { + font-size: smaller; +} +table.break-col-1 td.text-left:first-child { + word-break: break-word; +} +table.break-col-4 td.text-left:nth-child(4) { + word-break: break-word; +} +table.min-width-1-15 td.text-left:first-child { + min-width: 15em; +} +table.min-width-4-8 td.text-left:nth-child(4) { + min-width: 8em; +} + +/** Underline for abbreviations **/ + +abbr[title] { + text-decoration: underline solid #cdcdcd; +} + +/** Use the same style for right-details as for left-details **/ +.bottom-of-page .right-details { + font-size: var(--font-size--small); + display: block; +} + +/** Version switcher */ +button.version_select { + color: var(--color-foreground-primary); + background-color: var(--color-toc-background); + padding: 5px 10px; + border: none; +} + +.version_select:hover, .version_select:focus { + background-color: var(--color-sidebar-item-background--hover); +} + +.version_dropdown { + position: relative; + display: inline-block; + text-align: right; + font-size: var(--sidebar-item-font-size); +} + +.available_versions { + display: none; + position: absolute; + right: 0px; + background-color: var(--color-toc-background); + box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2); + z-index: 11; +} + +.available_versions a { + color: var(--color-foreground-primary); + padding: 12px 16px; + text-decoration: none; + display: block; +} + +.available_versions a:hover {background-color: var(--color-sidebar-item-background--current)} + +.show {display:block;} + +/** Fix for nested numbered list - the nested list is lettered **/ +ol.arabic ol.arabic { + list-style: lower-alpha; +} + +/** Make expandable sections look like links **/ +details summary { + color: var(--color-link); +} + +/** Context links at the bottom of the page **/ +footer { + font-size: var(--font-size--medium); +} diff --git a/doc/_static/css/github_issue_links.css b/doc/_static/css/github_issue_links.css new file mode 100644 index 000000000..af4be86ce --- /dev/null +++ b/doc/_static/css/github_issue_links.css @@ -0,0 +1,24 @@ +.github-issue-link-container { + padding-right: 0.5rem; +} +.github-issue-link { + font-size: var(--font-size--small); + font-weight: bold; + background-color: #DD4814; + padding: 13px 23px; + text-decoration: none; +} +.github-issue-link:link { + color: #FFFFFF; +} +.github-issue-link:visited { + color: #FFFFFF +} +.muted-link.github-issue-link:hover { + color: #FFFFFF; + text-decoration: underline; +} +.github-issue-link:active { + color: #FFFFFF; + text-decoration: underline; +} diff --git a/doc/_static/css/logo.css b/doc/_static/css/logo.css new file mode 100644 index 000000000..98d7cefc8 --- /dev/null +++ b/doc/_static/css/logo.css @@ -0,0 +1,7 @@ +.sidebar-brand.centered { + text-align: start; +} +.sidebar-logo { + max-width: 44px; + margin: initial; +} diff --git a/doc/_static/js/github_issue_links.js b/doc/_static/js/github_issue_links.js new file mode 100644 index 000000000..9eb945739 --- /dev/null +++ b/doc/_static/js/github_issue_links.js @@ -0,0 +1,25 @@ +window.onload = function() { + const link = document.createElement("a"); + link.classList.add("muted-link"); + link.classList.add("github-issue-link"); + link.text = "Give feedback"; + link.href = ( + "https://github.com/canonical/subiquity/issues/new?" + + "title=docs%3A+TYPE+YOUR+QUESTION+HERE" + + "&body=*Please describe the question or issue you're facing with " + + `"${document.title}"` + + ".*" + + "%0A%0A%0A%0A%0A" + + "---" + + "%0A" + + `*Reported+from%3A+${location.href}*` + ); + link.target = "_blank"; + + const div = document.createElement("div"); + div.classList.add("github-issue-link-container"); + div.append(link) + + const container = document.querySelector(".article-container > .content-icon-container"); + container.prepend(div); +}; diff --git a/doc/_static/ubuntu_logo.png b/doc/_static/ubuntu_logo.png new file mode 100644 index 000000000..41789147f Binary files /dev/null and b/doc/_static/ubuntu_logo.png differ diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 000000000..3d1ba86ac --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,131 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +import datetime +import os +import sys + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown: + +#sys.path.insert(0, os.path.abspath('../../')) +#sys.path.insert(0, os.path.abspath('../')) +#sys.path.insert(0, os.path.abspath('./')) +#sys.path.insert(0, os.path.abspath('.')) + +# -- Project information ----------------------------------------------------- + +project = 'Ubuntu Install Guide' +copyright = f'Canonical Group Ltd, {datetime.date.today().year}' + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +needs_sphinx = '5.1.1' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. + +extensions = [ + 'm2r2', + 'sphinx_copybutton', + 'sphinx_design', +] + + +# Add any paths that contain templates here, relative to this directory. + +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. + +# version = version.version_string() +# release = version + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. + +exclude_patterns = [ + ".sphinx/venv/*", +] + +# Sphinx-copybutton config options: +# 1) prompt to be stripped from copied code. +# 2) Set to copy all lines (not just prompt lines) to ensure multiline snippets +# can be copied even if they don't contain an EOF line. +copybutton_prompt_text = '$ ' +copybutton_only_copy_prompt_lines = False + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes: +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'furo' +html_logo = '_static/ubuntu_logo.png' +html_theme_options = { + 'light_css_variables': { + 'color-sidebar-background-border': 'none', + 'font-stack': 'Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif', + 'font-stack--monospace': 'Ubuntu Mono variable, Ubuntu Mono, Consolas, Monaco, Courier, monospace', + 'color-foreground-primary': '#111', + 'color-foreground-secondary': 'var(--color-foreground-primary)', + 'color-foreground-muted': '#333', + 'color-background-secondary': '#FFF', + 'color-background-hover': '#f2f2f2', + 'color-brand-primary': '#111', + 'color-brand-content': '#06C', + 'color-inline-code-background': 'rgba(0,0,0,.03)', + 'color-sidebar-link-text': '#111', + 'color-sidebar-item-background--current': '#ebebeb', + 'color-sidebar-item-background--hover': '#f2f2f2', + 'sidebar-item-line-height': '1.3rem', + 'color-link-underline': 'var(--color-background-primary)', + 'color-link-underline--hover': 'var(--color-background-primary)', + }, + 'dark_css_variables': { + 'color-foreground-secondary': 'var(--color-foreground-primary)', + 'color-foreground-muted': '#CDCDCD', + 'color-background-secondary': 'var(--color-background-primary)', + 'color-background-hover': '#666', + 'color-brand-primary': '#fff', + 'color-brand-content': '#06C', + 'color-sidebar-link-text': '#f7f7f7', + 'color-sidebar-item-background--current': '#666', + 'color-sidebar-item-background--hover': '#333', + }, +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named 'default.css' will overwrite the builtin 'default.css'. +html_static_path = ['_static'] + +# If you ever want to use the feedback button, turn on GH issues and then +# uncomment the github_issue_links files + +html_css_files = [ + 'css/logo.css', +# 'css/github_issue_links.css', + 'css/custom.css', +] +html_js_files = [ +# 'js/github_issue_links.js', +] diff --git a/doc/development/index.rst b/doc/development/index.rst new file mode 100644 index 000000000..7cc46ee82 --- /dev/null +++ b/doc/development/index.rst @@ -0,0 +1,33 @@ +Development +*********** + +Subiquity is an open source project that warmly welcomes community +projects, contributions, suggestions, fixes and constructive feedback. If you +would like to contribute to Subiquity, this set of documentation will help +orient you with our processes. + +----- + +Contributing +============ + +.. toctree:: + :maxdepth: 1 + +Debugging and reporting +======================= + +.. toctree:: + :maxdepth: 1 + +Testing +======= + +.. toctree:: + :maxdepth: 1 + +Documentation +============= + +.. toctree:: + :maxdepth: 1 diff --git a/doc/explanation/index.rst b/doc/explanation/index.rst new file mode 100644 index 000000000..fd7a2c2fc --- /dev/null +++ b/doc/explanation/index.rst @@ -0,0 +1,11 @@ +Explanation +*********** + +Our explanatory and conceptual guides are written to provide a better +understanding of how Subiquity works. They enable you to expand your +knowledge and become better at using and configuring Subiquity. + +----- + +.. toctree:: + :maxdepth: 1 diff --git a/doc/howto/index.rst b/doc/howto/index.rst new file mode 100644 index 000000000..b3c0b857e --- /dev/null +++ b/doc/howto/index.rst @@ -0,0 +1,19 @@ +.. _howto_index: + +How-to guides +************* + +If you have a specific goal in mind and are already familiar with the basics +of Subiquity, our how-to guides cover some of the more common operations +and tasks that you may need to complete. + +They will help you to achieve a particular end result, but may require you to +understand and adapt the steps to fit your specific requirements. + +----- + +How do I...? +============ + +.. toctree:: + :maxdepth: 1 diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 000000000..7c42d8b27 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,86 @@ +.. _index: + +Subiquity documentation +####################### + +A single sentence that says what the product is, succinctly and memorably +consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et +dolore magna aliqua. + +A paragraph of one to three short sentences, that describe what the product +does. Urna cursus eget nunc scelerisque viverra mauris in. Nibh mauris cursus +mattis molestie a iaculis at vestibulum rhoncus est pellentesque elit. Diam +phasellus vestibulum lorem sed. + +A third paragraph of similar length, this time explaining what need the product +meets. Dui ut ornare lectus sit amet est. Nunc sed augue lacus viverra vitae +congue eu consequat ac libero id faucibus nisl tincidunt eget nullam. + +Finally, a paragraph that describes whom the product is useful for. Nunc non +blandit massa enim nec dui nunc mattis enim. Ornare arcu odio ut sem nulla +pharetra diam porttitor leo a diam sollicitudin tempor id eu. Ipsum dolor sit +amet consectetur adipiscing elit pellentesque habitant. + +----- + +.. grid:: 1 1 2 2 + :gutter: 3 + + .. grid-item-card:: **Tutorial** + :link: tutorial/index + :link-type: doc + + Get started - a hands-on introduction to Subiquity for new users + + .. grid-item-card:: **How-to guides** + :link: howto/index + :link-type: doc + + Step-by-step guides covering key operations and common tasks + +.. grid:: 1 1 2 2 + :gutter: 3 + :reverse: + + .. grid-item-card:: **Reference** + :link: reference/index + :link-type: doc + + Technical information - specifications, APIs, architecture + + .. grid-item-card:: **Explanation** + :link: explanation/index + :link-type: doc + + Discussion and clarification of key topics + +Having trouble? We would like to help! +====================================== + +- Links to other communication channels go here + +Project and community +===================== + +Subiquity is a member of the Ubuntu family. It's an open source project that +warmly welcomes community projects, contributions, suggestions, fixes, and +constructive feedback. + +* Read our `Code of Conduct`_ +* IRC? +* Discourse? +* Contribute? +* Roadmap? + +.. toctree:: + :hidden: + :maxdepth: 2 + + tutorial/index + howto/index + reference/index + explanation/index + development/index + +.. Links: +.. _Code of Conduct: https://ubuntu.com/community/code-of-conduct diff --git a/doc/reference/index.rst b/doc/reference/index.rst new file mode 100644 index 000000000..66cd7560f --- /dev/null +++ b/doc/reference/index.rst @@ -0,0 +1,11 @@ +Reference +********* + +Our reference section contains support information for Subiquity. +This includes details on the network requirements, API definitions, support +matrices and so on. + +----- + +.. toctree:: + :maxdepth: 1 diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst new file mode 100644 index 000000000..bd71e58fe --- /dev/null +++ b/doc/tutorial/index.rst @@ -0,0 +1,30 @@ +.. _tutorial_index: + +Tutorials +********* + +This section contains step-by-step tutorials to help you get started with +Subiquity. We hope our tutorials make as few assumptions as possible and +are accessible to anyone with an interest in Subiquity. They should be a +great place to start learning about Subiquity, how it works, and what it's +capable of. + +----- + +Core tutorial +============= + + + +.. toctree:: + :maxdepth: 1 + +Quick-start tutorial +==================== + + + +.. toctree:: + :maxdepth: 1 + +