Merge pull request #1685 from s-makin/docs-RTD-setup

docs: add files for RTD setup

doc/.sphinx/requirements.txt

@@ -0,0 +1,6 @@
+furo
+m2r2
+sphinx==5.1.1
+sphinx_autobuild
+sphinx_copybutton
+sphinx_design

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)

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/`.

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);
+}

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;
+}

doc/_static/css/logo.css

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

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);
+};