From e90d85e78c53fdba56e8804f35142fdac76d6e6f Mon Sep 17 00:00:00 2001 From: Sally Makin Date: Fri, 26 May 2023 16:58:16 +0100 Subject: [PATCH 1/2] docs: add files for RTD setup - Add docs directory to keep files together - Add files necessary for RTD - Add style sheets for "Ubuntu" style - Add Diataxis outline and framework --- docs/.sphinx/requirements.txt | 6 + docs/Makefile | 66 +++++++ docs/_static/css/custom.css | 248 ++++++++++++++++++++++++ docs/_static/css/github_issue_links.css | 24 +++ docs/_static/css/logo.css | 7 + docs/_static/js/github_issue_links.js | 25 +++ docs/_static/ubuntu_logo.png | Bin 0 -> 7760 bytes docs/conf.py | 131 +++++++++++++ docs/development/index.rst | 33 ++++ docs/explanation/index.rst | 11 ++ docs/howto/index.rst | 19 ++ docs/index.rst | 86 ++++++++ docs/reference/index.rst | 11 ++ docs/tutorial/index.rst | 30 +++ 14 files changed, 697 insertions(+) create mode 100644 docs/.sphinx/requirements.txt create mode 100644 docs/Makefile create mode 100644 docs/_static/css/custom.css create mode 100644 docs/_static/css/github_issue_links.css create mode 100644 docs/_static/css/logo.css create mode 100644 docs/_static/js/github_issue_links.js create mode 100644 docs/_static/ubuntu_logo.png create mode 100644 docs/conf.py create mode 100644 docs/development/index.rst create mode 100644 docs/explanation/index.rst create mode 100644 docs/howto/index.rst create mode 100644 docs/index.rst create mode 100644 docs/reference/index.rst create mode 100644 docs/tutorial/index.rst diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt new file mode 100644 index 000000000..3ed17ae84 --- /dev/null +++ b/docs/.sphinx/requirements.txt @@ -0,0 +1,6 @@ +furo +m2r2 +sphinx==5.1.1 +sphinx_autobuild +sphinx_copybutton +sphinx_design diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..5f863f1d6 --- /dev/null +++ b/docs/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/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 000000000..eb525eb19 --- /dev/null +++ b/docs/_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/docs/_static/css/github_issue_links.css b/docs/_static/css/github_issue_links.css new file mode 100644 index 000000000..af4be86ce --- /dev/null +++ b/docs/_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/docs/_static/css/logo.css b/docs/_static/css/logo.css new file mode 100644 index 000000000..98d7cefc8 --- /dev/null +++ b/docs/_static/css/logo.css @@ -0,0 +1,7 @@ +.sidebar-brand.centered { + text-align: start; +} +.sidebar-logo { + max-width: 44px; + margin: initial; +} diff --git a/docs/_static/js/github_issue_links.js b/docs/_static/js/github_issue_links.js new file mode 100644 index 000000000..9eb945739 --- /dev/null +++ b/docs/_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/docs/_static/ubuntu_logo.png b/docs/_static/ubuntu_logo.png new file mode 100644 index 0000000000000000000000000000000000000000..41789147f47a570b81fc564918125675b856780e GIT binary patch literal 7760 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 literal 0 HcmV?d00001 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..3d1ba86ac --- /dev/null +++ b/docs/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/docs/development/index.rst b/docs/development/index.rst new file mode 100644 index 000000000..7cc46ee82 --- /dev/null +++ b/docs/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/docs/explanation/index.rst b/docs/explanation/index.rst new file mode 100644 index 000000000..fd7a2c2fc --- /dev/null +++ b/docs/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/docs/howto/index.rst b/docs/howto/index.rst new file mode 100644 index 000000000..b3c0b857e --- /dev/null +++ b/docs/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/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..7c42d8b27 --- /dev/null +++ b/docs/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/docs/reference/index.rst b/docs/reference/index.rst new file mode 100644 index 000000000..66cd7560f --- /dev/null +++ b/docs/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/docs/tutorial/index.rst b/docs/tutorial/index.rst new file mode 100644 index 000000000..bd71e58fe --- /dev/null +++ b/docs/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 + + From 8b16c25363445c0556dd3906968296afbaeb1aac Mon Sep 17 00:00:00 2001 From: Sally Makin Date: Wed, 7 Jun 2023 10:14:31 +0100 Subject: [PATCH 2/2] Add README.md and rename folder --- {docs => doc}/.sphinx/requirements.txt | 0 {docs => doc}/Makefile | 0 doc/README.md | 8 ++++++++ {docs => doc}/_static/css/custom.css | 0 {docs => doc}/_static/css/github_issue_links.css | 0 {docs => doc}/_static/css/logo.css | 0 {docs => doc}/_static/js/github_issue_links.js | 0 {docs => doc}/_static/ubuntu_logo.png | Bin {docs => doc}/conf.py | 0 {docs => doc}/development/index.rst | 0 {docs => doc}/explanation/index.rst | 0 {docs => doc}/howto/index.rst | 0 {docs => doc}/index.rst | 0 {docs => doc}/reference/index.rst | 0 {docs => doc}/tutorial/index.rst | 0 15 files changed, 8 insertions(+) rename {docs => doc}/.sphinx/requirements.txt (100%) rename {docs => doc}/Makefile (100%) create mode 100644 doc/README.md rename {docs => doc}/_static/css/custom.css (100%) rename {docs => doc}/_static/css/github_issue_links.css (100%) rename {docs => doc}/_static/css/logo.css (100%) rename {docs => doc}/_static/js/github_issue_links.js (100%) rename {docs => doc}/_static/ubuntu_logo.png (100%) rename {docs => doc}/conf.py (100%) rename {docs => doc}/development/index.rst (100%) rename {docs => doc}/explanation/index.rst (100%) rename {docs => doc}/howto/index.rst (100%) rename {docs => doc}/index.rst (100%) rename {docs => doc}/reference/index.rst (100%) rename {docs => doc}/tutorial/index.rst (100%) diff --git a/docs/.sphinx/requirements.txt b/doc/.sphinx/requirements.txt similarity index 100% rename from docs/.sphinx/requirements.txt rename to doc/.sphinx/requirements.txt diff --git a/docs/Makefile b/doc/Makefile similarity index 100% rename from docs/Makefile rename to doc/Makefile 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/docs/_static/css/custom.css b/doc/_static/css/custom.css similarity index 100% rename from docs/_static/css/custom.css rename to doc/_static/css/custom.css diff --git a/docs/_static/css/github_issue_links.css b/doc/_static/css/github_issue_links.css similarity index 100% rename from docs/_static/css/github_issue_links.css rename to doc/_static/css/github_issue_links.css diff --git a/docs/_static/css/logo.css b/doc/_static/css/logo.css similarity index 100% rename from docs/_static/css/logo.css rename to doc/_static/css/logo.css diff --git a/docs/_static/js/github_issue_links.js b/doc/_static/js/github_issue_links.js similarity index 100% rename from docs/_static/js/github_issue_links.js rename to doc/_static/js/github_issue_links.js diff --git a/docs/_static/ubuntu_logo.png b/doc/_static/ubuntu_logo.png similarity index 100% rename from docs/_static/ubuntu_logo.png rename to doc/_static/ubuntu_logo.png diff --git a/docs/conf.py b/doc/conf.py similarity index 100% rename from docs/conf.py rename to doc/conf.py diff --git a/docs/development/index.rst b/doc/development/index.rst similarity index 100% rename from docs/development/index.rst rename to doc/development/index.rst diff --git a/docs/explanation/index.rst b/doc/explanation/index.rst similarity index 100% rename from docs/explanation/index.rst rename to doc/explanation/index.rst diff --git a/docs/howto/index.rst b/doc/howto/index.rst similarity index 100% rename from docs/howto/index.rst rename to doc/howto/index.rst diff --git a/docs/index.rst b/doc/index.rst similarity index 100% rename from docs/index.rst rename to doc/index.rst diff --git a/docs/reference/index.rst b/doc/reference/index.rst similarity index 100% rename from docs/reference/index.rst rename to doc/reference/index.rst diff --git a/docs/tutorial/index.rst b/doc/tutorial/index.rst similarity index 100% rename from docs/tutorial/index.rst rename to doc/tutorial/index.rst