+
+
+ {%- if show_copyright %}
+
+ {%- if hasdoc('copyright') %}
+ {% trans path=pathto('copyright'), copyright=copyright|e -%}
+
Copyright © {{ copyright }}
+ {%- endtrans %}
+ {%- else %}
+ {% trans copyright=copyright|e -%}
+ Copyright © {{ copyright }}
+ {%- endtrans %}
+ {%- endif %}
+
+ {%- endif %}
+
+ {# mod: removed "Made with" #}
+
+ {%- if last_updated -%}
+
+ {% trans last_updated=last_updated|e -%}
+ Last updated on {{ last_updated }}
+ {%- endtrans -%}
+
+ {%- endif %}
+
+ {%- if show_source and has_source and sourcename %}
+
+ {%- endif %}
+
+
+
+ {# mod: replaced RTD icons with our links #}
+
+ {% if discourse %}
+
+ {% endif %}
+
+ {% if github_url and github_version and github_folder %}
+
+ {% if github_issues %}
+
+ {% endif %}
+
+
+ {% endif %}
+
+
+
+
Page not found
\n\nSorry, but the documentation page that you are looking for was not found.
\nDocumentation changes over time, and pages are moved around. We try to redirect you to the updated content where possible, but unfortunately, that didn\'t work this time (maybe because the content you were looking for does not exist in this version of the documentation).
\nYou can try to use the navigation to locate the content you\'re looking for, or search for a similar page.
\n',
+}
+
+# Default image for OGP (to prevent font errors, see
+# https://github.com/canonical/sphinx-docs-starter-pack/pull/54 )
+if not 'ogp_image' in locals():
+ ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg'
+
+############################################################
+### General configuration
+############################################################
+
+exclude_patterns = [
+ '_build',
+ 'Thumbs.db',
+ '.DS_Store',
+ '.sphinx',
+]
+exclude_patterns.extend(custom_excludes)
+
+rst_epilog = '''
+.. include:: /reuse/links.txt
+'''
+if 'custom_rst_epilog' in locals():
+ rst_epilog = custom_rst_epilog
+
+source_suffix = {
+ '.rst': 'restructuredtext',
+ '.md': 'markdown',
+}
+
+if not 'conf_py_path' in html_context and 'github_folder' in html_context:
+ html_context['conf_py_path'] = html_context['github_folder']
+
+# For ignoring specific links
+linkcheck_anchors_ignore_for_url = [
+ r'https://github\.com/.*'
+]
+linkcheck_anchors_ignore_for_url.extend(custom_linkcheck_anchors_ignore_for_url)
+
+############################################################
+### Styling
+############################################################
+
+# Find the current builder
+builder = 'dirhtml'
+if '-b' in sys.argv:
+ builder = sys.argv[sys.argv.index('-b')+1]
+
+# Setting templates_path for epub makes the build fail
+if builder == 'dirhtml' or builder == 'html':
+ templates_path = ['.sphinx/_templates']
+
+# Theme configuration
+html_theme = 'furo'
+html_last_updated_fmt = ''
+html_permalinks_icon = '¶'
+
+############################################################
+### Additional files
+############################################################
+
+html_static_path = ['.sphinx/_static']
+
+html_css_files = [
+ 'custom.css',
+ 'header.css',
+ 'github_issue_links.css',
+ 'furo_colors.css'
+]
+html_css_files.extend(custom_html_css_files)
+
+html_js_files = ['header-nav.js']
+if 'github_issues' in html_context and html_context['github_issues'] and not disable_feedback_button:
+ html_js_files.append('github_issue_links.js')
+html_js_files.extend(custom_html_js_files)
diff --git a/docs/custom_conf.py b/docs/custom_conf.py
new file mode 100644
index 000000000..7d3d73102
--- /dev/null
+++ b/docs/custom_conf.py
@@ -0,0 +1,151 @@
+import datetime
+
+# Custom configuration for the Sphinx documentation builder.
+# All configuration specific to your project should be done in this file.
+#
+# The file is included in the common conf.py configuration file.
+# You can modify any of the settings below or add any configuration that
+# is not covered by the common conf.py file.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+############################################################
+### Project information
+############################################################
+
+# Product name
+project = 'Documentation starter pack'
+author = 'Canonical Group Ltd'
+
+# Uncomment if your product uses release numbers
+# release = '1.0'
+
+# The default value uses the current year as the copyright year.
+#
+# 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, %s' % (datetime.date.today().year, author)
+
+## Open Graph configuration - defines what is displayed in the website preview
+# The URL of the documentation output
+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
+# 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 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 your product website (without "https://")
+ 'product_page': 'documentation.ubuntu.com',
+
+ # Add your product tag 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 GitHub info for your project
+ 'github_url': 'https://github.com/canonical/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': '/',
+
+ # 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"
+}
+
+# If your project is on documentation.ubuntu.com, specify the project
+# slug (for example, "lxd") here.
+slug = ""
+
+############################################################
+### Redirects
+############################################################
+
+# Set up redirects (https://documatt.gitlab.io/sphinx-reredirects/usage.html)
+# For example: 'explanation/old-name.html': '../how-to/prettify.html',
+
+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)
+
+custom_linkcheck_anchors_ignore_for_url = [
+ ]
+
+############################################################
+### Additions to default configuration
+############################################################
+
+## The following settings are appended to the default configuration.
+## Use them to extend the default functionality.
+
+# Add extensions
+custom_extensions = []
+
+# Add files or directories that should be excluded from processing.
+custom_excludes = [
+ 'doc-cheat-sheet*',
+]
+
+# Add CSS files (located in .sphinx/_static/)
+custom_html_css_files = []
+
+# Add JavaScript files (located in .sphinx/_static/)
+custom_html_js_files = []
+
+## The following settings override the default configuration.
+
+# Specify a reST string that is included at the end of each file.
+# If commented out, use the default (which pulls the reuse/links.txt
+# file into each reST file).
+# custom_rst_epilog = ''
+
+# 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
+
+############################################################
+### Additional configuration
+############################################################
+
+## Add any configuration that is not covered by the common conf.py file.
diff --git a/docs/doc-cheat-sheet-myst.md b/docs/doc-cheat-sheet-myst.md
new file mode 100644
index 000000000..19b07f531
--- /dev/null
+++ b/docs/doc-cheat-sheet-myst.md
@@ -0,0 +1,243 @@
+---
+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.
+
+Also see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/index.html) for detailed information, 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)=
+## Links
+
+- [Canonical website](https://canonical.com/)
+- 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
+ 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
+
+
+
+```{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.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}
+
+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 terminal view with input and output:
+
+```{terminal}
+ :input: command
+ :user: root
+ :host: vampyr
+
+the output
+```
+
+A link to a YouTube video:
+
+```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0
+ :title: Demo
+```
diff --git a/docs/doc-cheat-sheet.rst b/docs/doc-cheat-sheet.rst
new file mode 100644
index 000000000..b12ebcdf7
--- /dev/null
+++ b/docs/doc-cheat-sheet.rst
@@ -0,0 +1,258 @@
+:orphan:
+
+.. _cheat-sheet:
+
+reStructuredText cheat sheet
+============================
+
+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 |
++----------------------+------------+
+
+.. 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 terminal view with input and output:
+
+.. terminal::
+ :input: command
+ :user: root
+ :host: vampyr
+
+ the output
+
+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/index.md b/docs/index.md
new file mode 100644
index 000000000..16f572f3e
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,31 @@
+Ubuntu Pro For Windows
+======================
+
+Ubuntu Pro for Windows is a desktop application that provides compliance services for WSL instances.
+
+It manages Ubuntu WSL instances, by pro-attaching them and establishing a connection with Landscape.
+
+In a large organisation many repetitive steps are required to ensure compliance; Ubuntu Pro for Windows automates this work across an enterprise landscape.
+
+Ubuntu Pro for Windows is of value to corporate security teams, system administrators and desktop users, all of whom would otherwise need to manage instances individually and manually.
+
+## Project and community
+
+Example Project is a member of the Ubuntu family. It’s an open source project that warmly welcomes community contributions, suggestions, fixes and constructive feedback.
+
+* Code of conduct
+* Get support
+* Join our online chat
+* Contribute
+* Roadmap
+
+Thinking about using Example Product for your next project? Get in touch!
+
+
+```{toctree}
+:hidden:
+
+Install
+Windows Agent command line interface
+WSL Pro Service command line interface
+```
diff --git a/doc/02.-Installation.md b/docs/install.md
similarity index 95%
rename from doc/02.-Installation.md
rename to docs/install.md
index 43028de57..8df6d6cc1 100644
--- a/doc/02.-Installation.md
+++ b/docs/install.md
@@ -1,14 +1,15 @@
-# Installing Ubuntu Pro For Windows
+# How to install Ubuntu Pro for Windows
+
This guide will show you how to install Ubuntu Pro For Windows for local development and testing.
-### Requirements
+## Requirements
- A Windows machine with access to the internet
- Appx from the Microsoft Store:
- Windows Subsystem For Linux
- Either Ubuntu, Ubuntu 22.04, or Ubuntu (Preview)
- The Windows Subsystem for Windows optional feature enabled
-### Download
+## Download
1. Go to the [repository actions page](https://github.com/canonical/ubuntu-pro-for-windows/actions/workflows/qa-azure.yaml?query=branch%3Amain+).
2. Click the latest successful workflow run.
@@ -17,7 +18,7 @@ This guide will show you how to install Ubuntu Pro For Windows for local develop
- Windows agent: UbuntuProForWindows+...
- WSL-Pro-Service: Wsl-pro-service_…
-### Install the Windows agent
+## Install the Windows agent
This is the Windows-side agent that manages the distros.
1. Uninstall Ubuntu Pro For Windows if you had installed previously:
```powershell
@@ -36,7 +37,7 @@ This is the Windows-side agent that manages the distros.
8. The GUI should show up. You’re done.
-### Install the WSL Pro Service
+## Install the WSL Pro Service
This is the Linux-side component that talks to the agent. Choose one or more distros Jammy or greater, and follow the instructions.
1. Uninstall the WSL-Pro-Service from your distro if you had it installed previously:
```bash
@@ -57,8 +58,8 @@ This is the Linux-side component that talks to the agent. Choose one or more dis
systemctl status wsl-pro.service
```
-# Tests and utilities
-## Enabling Pro
+## Tests and utilities
+### Enabling Pro
If you’ve completed the installation, you may want to check that it worked. To do so, follow these steps:
1. Go to your [Ubuntu Pro dashboard](https://ubuntu.com/pro/dashboardand) to get your Ubuntu Pro token.
2. Go to the Windows menu, and search and click Ubuntu Pro For Windows. If it does not show up, your installation of the agent went wrong.
@@ -70,7 +71,7 @@ If you’ve completed the installation, you may want to check that it worked. To
```
6. If the distro is pro-attached, the installation was successful.
-## Landscape registration
+### Landscape registration
You can use a private Landscape instance (different from [landscape.canonical.com](landscape.canonical.com)). It must be over HTTP, as using certificates is not yet supported. To do so, follow these steps:
1. Press Windows+R.
2. Write regedit.exe and enter.
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 000000000..954237b9b
--- /dev/null
+++ b/docs/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/readme.rst b/docs/readme.rst
new file mode 100644
index 000000000..fc6fd84ff
--- /dev/null
+++ b/docs/readme.rst
@@ -0,0 +1,284 @@
+Documentation starter pack
+==========================
+
+See the `Sphinx and Read the Docs `_ guide for instructions on how to get started with Sphinx documentation.
+
+Then go through the following sections to use this starter pack to set up your docs repository.
+
+Set up your documentation repository
+------------------------------------
+
+You can either create a standalone documentation project based on this repository or include the files from this repository in a dedicated documentation folder in an existing code repository.
+
+**Note:** We're planning to provide the contents of this repository as an installable package in the future, but currently, you need to copy and update the required files manually.
+
+Standalone documentation repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To create a standalone documentation repository, clone this starter pack
+repository, `update the configuration <#configure-the-documentation>`_, and
+then commit all files to the documentation repository.
+
+You don't need to move any files, and you don't need to do any special
+configuration on Read the Docs.
+
+Here is one way to do this for newly-created fictional docs repository
+``canonical/alpha-docs``:
+
+.. code-block:: none
+
+ git clone git@github.com:canonical/sphinx-docs-starter-pack alpha-docs
+ cd alpha-docs
+ rm -rf .git
+ git init
+ git branch -m main
+ UPDATE THE CONFIGURATION AND BUILD THE DOCS
+ git add -A
+ git commit -m "Import sphinx-docs-starter-pack"
+ git remote add upstream git@github.com:canonical/alpha-docs
+ git push -f upstream main
+
+Documentation in a code repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To add documentation to an existing code repository:
+
+#. create a directory called ``docs`` at the root of the code repository
+#. populate the above directory with the contents of the starter pack
+ repository (with the exception of the ``.git`` directory)
+#. copy the file(s) located in the ``docs/.github/workflows`` directory into
+ the code repository's ``.github/workflows`` directory
+#. in the above workflow file(s), change the value of the ``working-directory`` field from ``.`` to ``docs``
+#. in file ``docs/.readthedocs.yaml`` set the following:
+
+ * ``configuration: docs/conf.py``
+ * ``requirements: docs/.sphinx/requirements.txt``
+
+**Note:** When configuring RTD itself for your project, the setting "Path for
+``.readthedocs.yaml``" (under **Advanced Settings**) will need to be given the
+value of ``docs/.readthedocs.yaml``.
+
+Getting started
+---------------
+
+There are make targets defined in the ``Makefile`` that do various things. To
+get started, we will:
+
+* install prerequisite software
+* view the documentation
+
+Install prerequisite software
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To install the prerequisites:
+
+.. code-block:: none
+
+ make install
+
+This will create a virtual environment (``.sphinx/venv``) and install
+dependency software (``.sphinx/requirements.txt``) within it.
+
+**Note**:
+By default, the starter pack uses the latest compatible version of all tools and does not pin its requirements.
+This might change temporarily if there is an incompatibility with a new tool version.
+There is therefore no need in using a tool like Renovate to automatically update the requirements.
+
+View the documentation
+~~~~~~~~~~~~~~~~~~~~~~
+
+To view the documentation:
+
+.. code-block:: none
+
+ make run
+
+This will do several things:
+
+* activate the virtual environment
+* build the documentation
+* serve the documentation on **127.0.0.1:8000**
+* rebuild the documentation each time a file is saved
+* send a reload page signal to the browser when the documentation is rebuilt
+
+The ``run`` target is therefore very convenient when preparing to submit a
+change to the documentation.
+
+Local checks
+~~~~~~~~~~~~
+
+Before committing and pushing changes, it's a good practice to run various checks locally to catch issues early in the development process.
+
+Local build
+^^^^^^^^^^^
+
+Run a clean build of the docs to surface any build errors that would occur in RTD:
+
+.. code-block:: none
+
+ make clean-doc
+ make html
+
+Spelling check
+^^^^^^^^^^^^^^
+
+Ensure there are no spelling errors in the documentation:
+
+.. code-block:: shell
+
+ make spelling
+
+Inclusive language check
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Ensure the documentation uses inclusive language:
+
+.. code-block:: shell
+
+ make woke
+
+Link check
+^^^^^^^^^^
+
+Validate links within the documentation:
+
+.. code-block:: shell
+
+ make linkcheck
+
+Configure the documentation
+---------------------------
+
+You must modify some of the default configuration to suit your project.
+To simplify keeping your documentation in sync with the starter pack, all custom configuration is located in the ``custom_conf.py`` file.
+You should never modify the common ``conf.py`` file.
+
+Go through all settings in the ``Project information`` section of the ``custom_conf.py`` file and update them for your project.
+
+See the following sections for further customisation.
+
+Configure the header
+~~~~~~~~~~~~~~~~~~~~
+
+By default, the header contains your product tag, product name (taken from the ``project`` setting in the ``custom_conf.py`` file), a link to your product page, and a drop-down menu for "More resources" that contains links to Discourse and GitHub.
+
+You can change any of those links or add further links to the "More resources" drop-down by editing the ``.sphinx/_templates/header.html`` file.
+For example, you might want to add links to announcements, tutorials, getting started guides, or videos that are not part of the documentation.
+
+Configure the spelling check
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your documentation uses US English instead of UK English, change this in the
+``.sphinx/spellingcheck.yaml`` file.
+
+To add exceptions for words the spelling check marks as wrong even though they are correct, edit the ``.custom_wordlist.txt`` file.
+You shouldn't edit ``.wordlist.txt``, because this file is maintained and updated centrally and contains words that apply across all projects.
+
+Configure the inclusive-language check
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you can't avoid non-inclusive language in some cases, you'll need to
+configure exemptions for them.
+
+In-file exemptions
+^^^^^^^^^^^^^^^^^^
+
+Suppose a reST file has a link to some site you don't control, and the address
+contains "\m\a\s\t\e\r" — a non-inclusive word. You can't change the link,
+but the remainder of the file must be checked for inclusive language. Here the
+``woke`` tool's `next-line ignore
+`_ feature is
+useful, as follows.
+
+If the link is in-line, move the definition to a line of its own (e.g. among
+``.. LINKS`` at the bottom of the file). Above the definition, invoke the
+``wokeignore`` rule for the offending word:
+
+.. code-block:: ReST
+
+ .. LINKS
+ .. wokeignore:rule=master
+ .. _link anchor: https://some-external-site.io/master/some-page.html
+
+Exempt an entire file
+^^^^^^^^^^^^^^^^^^^^^
+
+If it's necessary *and safe*, you can exempt a whole file from
+inclusive-language checks. To exempt ``docs/foo/bar.rst`` for example, add the
+following line to ``.wokeignore``:
+
+.. code-block:: none
+
+ foo/bar.rst
+
+.. note::
+
+ For ``.wokeignore`` to take effect, you must also move it into your
+ project's root directory. If you leave it in ``docs/``, the ``woke`` tool
+ won't find it and no files will be exempt.
+
+Change checked file-types and locations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, only reST files are checked for inclusive language — and only those
+in the documentation folder (usually ``docs/``) and its subfolders. To check
+Markdown files for example, or files outside the ``docs/`` subtree, you must
+change how the ``woke`` tool is invoked.
+
+The ``woke`` command is issued from ``docs/Makefile``. The command's syntax
+is out of scope here — consult the `woke User Guide
+`_.
+
+Configure the link check
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have links in the documentation that you don't want to be checked (for
+example, because they are local links or give random errors even though they
+work), you can add them to the ``linkcheck_ignore`` variable in the ``custom_conf.py`` file.
+
+Activate/deactivate feedback button
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A feedback button is included by default, which appears at the top of each page
+in the documentation. It redirects users to your GitHub issues page, and
+populates an issue for them with details of the page they were on when they
+clicked the button.
+
+If your project does not use GitHub issues, set the ``github_issues`` variable
+in the ``custom_conf.py`` file to an empty value to disable both the feedback button
+and the issue link in the footer.
+If you want to deactivate only the feedback button, but keep the link in the
+footer, set ``disable_feedback_button`` in the ``custom_conf.py`` file to ``True``.
+
+Add redirects
+~~~~~~~~~~~~~
+
+You can add redirects to make sure existing links and bookmarks continue working when you move files around.
+To do so, specify the old and new paths in the ``redirects`` setting of the ``custom_conf.py`` file.
+
+Add custom configuration
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To add custom configurations for your project, see the ``Additions to default configuration`` and ``Additional configuration`` sections in the ``custom_conf.py`` file.
+These can be used to extend or override the common configuration, or to define additional configuration that is not covered by the common ``conf.py`` file.
+
+(Optional) Synchronise GitHub issues to Jira
+--------------------------------------------
+
+If you wish to sync issues from your documentation repository on GitHub to your
+Jira board, configure the `GitHub/Jira sync bot `_
+by editing the ``.github/workflows/.jira_sync_config.yaml`` file appropriately.
+In addition to updating this file, you must also apply server configuration
+for this feature to work. For more information, see `server configuration details `_
+for the GitHub/Jira sync bot.
+
+The ``.jira_sync_config.yaml`` file that is included in the starter pack
+contains configuration for syncing issues from the starter pack repository to
+its documentation Jira board.
+Therefore, it does not work out of the box for other repositories in GitHub,
+and you must update it if you want to use the synchronisation feature.
+
+Change log
+----------
+
+See the `change log `_ for a list of relevant changes to the starter pack.
diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt
new file mode 100644
index 000000000..04cfff56e
--- /dev/null
+++ b/docs/reuse/links.txt
@@ -0,0 +1,4 @@
+.. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/
+.. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs
+.. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs
+.. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/
diff --git a/doc/03.-Windows-Agent-command-line-reference.md b/docs/windows-agent-command-line-reference.md
similarity index 100%
rename from doc/03.-Windows-Agent-command-line-reference.md
rename to docs/windows-agent-command-line-reference.md
diff --git a/doc/04.-WSL-Pro-Service-command-line-reference.md b/docs/wsl-pro-service-command-line-reference.md
similarity index 98%
rename from doc/04.-WSL-Pro-Service-command-line-reference.md
rename to docs/wsl-pro-service-command-line-reference.md
index 155c28553..1f22e2a02 100644
--- a/doc/04.-WSL-Pro-Service-command-line-reference.md
+++ b/docs/wsl-pro-service-command-line-reference.md
@@ -1,4 +1,4 @@
-The WSL Pro Service is the component that runs on each guest Ubuntu distro.
+The Windows Agent is the component that runs on the host Windows machine.
## Usage
diff --git a/go.work.sum b/go.work.sum
index 0590acdf8..9fe10e92d 100644
--- a/go.work.sum
+++ b/go.work.sum
@@ -582,6 +582,7 @@ github.com/nats-io/nuid v1.0.1/go.mod h1:19wcPz3Ph3q0Jbyiqsd0kePYG7A95tJPxeL+1OS
github.com/pascaldekloe/goe v0.0.0-20180627143212-57f6aae5913c/go.mod h1:lzWF7FIEvWOWxwDKqyGYQf6ZUaNfKdP144TG7ZOy1lc=
github.com/pascaldekloe/goe v0.1.0/go.mod h1:lzWF7FIEvWOWxwDKqyGYQf6ZUaNfKdP144TG7ZOy1lc=
github.com/pelletier/go-toml v1.9.5 h1:4yBQzkHv+7BHq2PQUZF3Mx0IYxG7LsP222s7Agd3ve8=
+github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
github.com/pkg/sftp v1.10.0/go.mod h1:NxmoDg/QLVWluQDUYG7XBZTLUpKeFa8e3aMf1BfjyHk=
github.com/pkg/sftp v1.10.1/go.mod h1:lYOWFsE0bwd1+KfKJaKeuokY15vzFx25BLbzYYoAxZI=
github.com/posener/complete v1.1.1/go.mod h1:em0nMJCgc9GFtwrmVmEMR/ZL6WyhyjMBndrE9hABlRI=
diff --git a/windows-agent/generate/generate.yaml b/windows-agent/generate/generate.yaml
index 492d42055..2f33b4f01 100644
--- a/windows-agent/generate/generate.yaml
+++ b/windows-agent/generate/generate.yaml
@@ -1,7 +1,7 @@
project-root: ".."
docs:
readme: README.md
- docs: ../doc/03.-Windows-Agent-command-line-reference.md
+ docs: ../docs/windows-agent-command-line-reference.md
man: generated/usr/share,
completions: generated/usr/share
i18n:
diff --git a/windows-agent/internal/grpc/logstreamer/test/log_test.pb.go b/windows-agent/internal/grpc/logstreamer/test/log_test.pb.go
index 411401fd4..dd8654c00 100644
--- a/windows-agent/internal/grpc/logstreamer/test/log_test.pb.go
+++ b/windows-agent/internal/grpc/logstreamer/test/log_test.pb.go
@@ -1,6 +1,6 @@
// Code generated by protoc-gen-go. DO NOT EDIT.
// versions:
-// protoc-gen-go v1.28.1
+// protoc-gen-go v1.31.0
// protoc v3.21.12
// source: log_test.proto
diff --git a/wsl-pro-service/generate/generate.yaml b/wsl-pro-service/generate/generate.yaml
index e7b46c445..463106fd3 100644
--- a/wsl-pro-service/generate/generate.yaml
+++ b/wsl-pro-service/generate/generate.yaml
@@ -1,7 +1,7 @@
project-root: ".."
docs:
readme: README.md
- docs: ../doc/04.-WSL-Pro-Service-command-line-reference.md
+ docs: ../docs/wsl-pro-service-command-line-reference.md
man: generated/usr/share,
completions: generated/usr/share
i18n:
diff --git a/wsl-pro-service/internal/grpc/logstreamer/test/log_test.pb.go b/wsl-pro-service/internal/grpc/logstreamer/test/log_test.pb.go
index 3cfb0daa9..ef59a5481 100644
--- a/wsl-pro-service/internal/grpc/logstreamer/test/log_test.pb.go
+++ b/wsl-pro-service/internal/grpc/logstreamer/test/log_test.pb.go
@@ -1,6 +1,6 @@
// Code generated by protoc-gen-go. DO NOT EDIT.
// versions:
-// protoc-gen-go v1.28.1
+// protoc-gen-go v1.31.0
// protoc v3.21.12
// source: log_test.proto
+
{{ project }} ++ +
+
+
+
+