docs: merge wsl docs repos

docs/.custom_wordlist.txt

@@ -9,25 +9,34 @@ remediations
 # Tools and brands
 apport
 appx
+AppxPackage
 Center
 CIS
 Codecov
+cuda
 distro
 distros
 ESM
 gRPC
+IDEs
+js
 Intune
 macOS
 MSIX
+npm
+OpenGL
+OpenVINO
 powershell
 PowerShell
 structurizr
 Structurizr
 systemd
 ubuntu
 UbuntuProForWSL
+winget
 wsl
 WSL
+WSLg
 WSL's
 zsh
 Postfix
@@ -44,18 +53,23 @@ compinit
 config
 dev
 gapped
+gpg
 grpc
 https
 init
+filesystem
 FIPS
 fpath
 FQDN
 HIPAA
 Hostagent
 JWT
+localhost
 LTS
+Numbat
 os
 pem
+PRs
 repo
 rootfs
 SLA
@@ -65,6 +79,10 @@ ssl
 tcp
 toolchain
 url
+vGPU
+webserver
+whitepaper
+whitespace
 zshrc
 ESM
 Ok

docs/custom_conf.py

@@ -19,13 +19,13 @@
 ############################################################
 
 # Product name
-project = 'Ubuntu Pro for WSL'
-author = 'Canonical Ltd.'
+project = "Ubuntu on WSL"
+author = "Canonical Ltd."
 
 # The title you want to display for the documentation in the sidebar.
 # You might want to include a version number here.
 # To not display any title, set this option to an empty string.
-html_title = project + ' documentation'
+html_title = project + " documentation"
 
 # The default value uses CC-BY-SA as the license and the current year
 # as the copyright year.
@@ -48,73 +48,62 @@
 #   -H 'Accept: application/vnd.github.v3.raw' \
 #   https://api.github.com/repos/canonical/<REPO> | jq '.created_at'
 
-copyright = '%s CC-BY-SA, %s' % (datetime.date.today().year, author)
+copyright = "%s CC-BY-SA, %s" % (datetime.date.today().year, author)
 
 ## Open Graph configuration - defines what is displayed as a link preview
 ## when linking to the documentation from another website (see https://ogp.me/)
 # The URL where the documentation will be hosted (leave empty if you
 # don't know yet)
 # NOTE: If no ogp_* variable is defined (e.g. if you remove this section) the
 # sphinxext.opengraph extension will be disabled.
-ogp_site_url = 'https://canonical-starter-pack.readthedocs-hosted.com/'
+ogp_site_url = "https://canonical-starter-pack.readthedocs-hosted.com/"
 # The documentation website name (usually the same as the product name)
 ogp_site_name = project
 # The URL of an image or logo that is used in the preview
-ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg'
+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 = '../msix/UbuntuProForWSL/Images/icon.ico'
+html_favicon = "../msix/UbuntuProForWSL/Images/icon.ico"
 
 # (Some settings must be part of the html_context dictionary, while others
 #  are on root level. Don't move the settings.)
 html_context = {
-
     # Change to the link to the website of your product (without "https://")
     # For example: "ubuntu.com/lxd" or "microcloud.is"
     # If there is no product website, edit the header template to remove the
     # link (see the readme for instructions).
-    'product_page': 'documentation.ubuntu.com',
-
+    "product_page": "ubuntu.com/wsl",
     # Add your product tag (the orange part of your logo, will be used in the
     # header) to ".sphinx/_static" and change the path here (start with "_static")
     # (default is the circle of friends)
-    'product_tag': '_static/tag.png',
-
+    "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/c/wsl/27',
-
+    "discourse": "https://discourse.ubuntu.com/c/wsl/27",
     # Change to the Mattermost channel you want to link to
     # (use an empty value if you don't want to link)
     # 'mattermost': 'https://chat.canonical.com/canonical/channels/documentation',
-
     # Change to the GitHub info for your project
-    'github_url': 'https://github.com/canonical/ubuntu-pro-for-wsl',
+    "github_url": "https://github.com/canonical/ubuntu-pro-for-wsl",
     # Change to the Matrix channel you want to link to
     # (use an empty value if you don't want to link)
-    # 'matrix': 'https://matrix.to/#/#documentation:ubuntu.com',
-
+    "matrix": "https://matrix.to/#/#ubuntu-wsl:ubuntu.com",
     # Change to the branch for this version of the documentation
-    'github_version': 'main',
-
+    "github_version": "main",
     # Change to the folder that contains the documentation
     # (usually "/" or "/docs/")
-    'github_folder': '/docs/',
-
+    "github_folder": "/docs/",
     # 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',
-
+    "github_issues": "enabled",
     # Controls the existence of Previous / Next buttons at the bottom of pages
     # Valid options: none, prev, next, both
-    'sequential_nav': "none",
-
+    "sequential_nav": "none",
     # Controls if to display the contributors of a file or not
     "display_contributors": True,
-
     # Controls time frame for showing the contributors
-    "display_contributors_since": ""
+    "display_contributors_since": "",
 }
 
 # If your project is on documentation.ubuntu.com, specify the project
@@ -131,21 +120,41 @@
 # (see https://docs.readthedocs.io/en/stable/guides/redirects.html).
 # NOTE: If this variable is not defined, set to None, or the dictionary is empty,
 # the sphinx_reredirects extension will be disabled.
-redirects = {}
+
+# NOTE: content from these tutorials will be reworked for inclusion in other tutorials
+# for now we can link to the versions available on the original GitHub repo
+redirects = {
+    # deprecated tutorials that will be reworked into new content
+    "tutorials/dotnet-systemd": "https://github.com/ubuntu/WSL/blob/main/docs/tutorials/dotnet-systemd.md",
+    "tutorials/interop": "https://github.com/ubuntu/WSL/blob/main/docs/tutorials/interop.md",
+    # tutorials that have since been converted to howto guides
+    "tutorials/cloud-init": "../../howto/cloud-init",
+    "tutorials/data-science-and-engineering": "../../howto/data-science-and-engineering",
+    "tutorials/gpu-cuda": "../../howto/gpu-cuda",
+    "tutorials/vscode": "../../tutorial/develop-with-ubuntu-wsl",
+    # the term "guides" was used in the original repo
+    "guides/contributing": "../../howto/contributing",
+    "guides/install-ubuntu-wsl2": "../../howto/install-ubuntu-wsl2",
+    "guides/run-workflows-azure": "../../howto/run-workflows-azure",
+    # improved url
+    "tutorial/getting-started": "../../tutorial/getting-started-with-up4w",
+    # redundant after merge
+    "explanations/up4w": "../../",
+}
 
 ############################################################
 ### Link checker exceptions
 ############################################################
 
 # Links to ignore when checking links
 linkcheck_ignore = [
-    'http://127.0.0.1:8000',
+    "http://127.0.0.1:8000",
     # Linkcheck does not have access to the repo
-    'https://github.com/canonical/ubuntu-pro-for-wsl/*',
+    "https://github.com/canonical/ubuntu-pro-for-wsl/*",
     # This page redirects to SSO login:
-    'https://ubuntu.com/pro/dashboard',
+    "https://ubuntu.com/pro/dashboard",
     # Only users logged in to MS Store with their account registered for beta can access this link
-    'https://apps.microsoft.com/detail/9PD1WZNBDXKZ',
+    "https://apps.microsoft.com/detail/9PD1WZNBDXKZ",
 ]
 
 # Pages on which to ignore anchors
@@ -168,13 +177,13 @@
 # not need to be added here: myst_parser, sphinx_copybutton, sphinx_design,
 # sphinx_reredirects, sphinxcontrib.jquery, sphinxext.opengraph
 custom_extensions = [
-    'sphinx_tabs.tabs',
-    'canonical.youtube-links',
-    'canonical.related-links',
-    'canonical.custom-rst-roles',
-    'canonical.terminal-output',
-    'notfound.extension'
-    ]
+    "sphinx_tabs.tabs",
+    "canonical.youtube-links",
+    "canonical.related-links",
+    "canonical.custom-rst-roles",
+    "canonical.terminal-output",
+    "notfound.extension",
+]
 
 # Add custom required Python modules that must be added to the
 # .sphinx/requirements.txt file.
@@ -187,9 +196,9 @@
 
 # Add files or directories that should be excluded from processing.
 custom_excludes = [
-    'doc-cheat-sheet*',
-    'diagrams/readme.md',
-    ]
+    "doc-cheat-sheet*",
+    "diagrams/readme.md",
+]
 
 # Add CSS files (located in .sphinx/_static/)
 custom_html_css_files = []
@@ -223,7 +232,14 @@
 ## Add any configuration that is not covered by the common conf.py file.
 
 # Define a :center: role that can be used to center the content of table cells.
-rst_prolog = '''
+rst_prolog = """
 .. role:: center
    :class: align-center
-'''
+"""
+
+# Define a selector that only adds copy buttons to code blocks without the class `no-copy`
+copybutton_selector = "div:not(.no-copy) > div.highlight > pre"
+
+# Define prompts to be excluded from copying when a copy button is used
+copybutton_prompt_text = r"^.*?[\$>]\s+"
+copybutton_prompt_is_regexp = True