Merge remote-tracking branch 'origin/main' into work/hotfix-7.5-merge

Signed-off-by: Sergio Schvezov <[email protected]>

.github/workflows/spread.yml

@@ -38,7 +38,6 @@ jobs:
       fail-fast: false
       matrix:
         spread-jobs:
-          - google:ubuntu-18.04-64
           - google:ubuntu-20.04-64
           - google:ubuntu-22.04-64
 
@@ -113,7 +112,7 @@ jobs:
           SNAPCRAFT_STORE_CREDENTIALS_STAGING: "${{ secrets.SNAPCRAFT_STORE_CREDENTIALS_STAGING }}"
           SNAPCRAFT_STORE_CREDENTIALS_STAGING_CANDID: "${{ secrets.SNAPCRAFT_STORE_CREDENTIALS_STAGING_CANDID }}"
           SNAPCRAFT_STORE_CREDENTIALS_STAGING_LEGACY: "${{ secrets.SNAPCRAFT_STORE_CREDENTIALS_STAGING_LEGACY }}"
-        run: spread google:ubuntu-18.04-64:tests/spread/general/store
+        run: spread google:ubuntu-22.04-64:tests/spread/general/store
 
       - name: Discard spread workers
         if: always()

.gitignore

@@ -11,6 +11,9 @@ demos/*/stage/
 dist
 docs/**.html
 docs/reference.md
+docs/reference/commands
+docs/.sphinx
+docs/_build
 *.egg-info
 .eggs/
 .envrc

.gitmodules

@@ -1,6 +1,3 @@
-[submodule "docs"]
-	path = docs
-	url = https://github.com/CanonicalLtd/snappy-docs.git
 [submodule "tests/spread/tools/snapd-testing-tools"]
 	path = tests/spread/tools/snapd-testing-tools
 	url = https://github.com/snapcore/snapd-testing-tools.git

.readthedocs.yaml

@@ -0,0 +1,34 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+---
+# Required
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.8"
+  apt_packages:
+    - libapt-pkg-dev
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  builder: html
+  fail_on_warning: true
+
+# Build documentation with MkDocs
+# mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF
+#formats:
+#  - pdf
+
+# Optionally set the version of Python
+# and requirements required to build your docs
+python:
+  install:
+    - requirements: docs/.sphinx/requirements.txt
+    - requirements: docs/requirements.txt

docs/.sphinx/pinned-requirements.txt

@@ -16,7 +16,7 @@ pyenchant==3.2.2
 Pygments==2.13.0
 pyparsing==3.0.9
 pytz==2022.6
-requests==2.28.1
+requests==2.31.0
 six==1.16.0
 snowballstemmer==2.2.0
 soupsieve==2.3.2.post1
@@ -30,5 +30,5 @@ sphinxcontrib-htmlhelp==2.0.0
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.5
-tornado==6.2
+tornado==6.3.2
 urllib3==1.26.13

docs/.sphinx/requirements.txt

@@ -8,4 +8,3 @@ sphinx-reredirects
 pyspelling
 sphinx-copybutton
 sphinx-pydantic
-sphinx-toolbox

docs/Makefile

@@ -17,7 +17,7 @@ help:
 install:
 	@echo "... setting up virtualenv"
 	python3 -m venv .sphinx/venv
-	. $(VENV); pip install --upgrade -r .sphinx/requirements.txt
+	. $(VENV); pip install --upgrade -r .sphinx/requirements.txt -r requirements.txt
 
 	@echo "\n" \
 		"--------------------------------------------------------------- \n" \
@@ -39,6 +39,7 @@ serve:
 
 clean: clean-doc
 	rm -rf .sphinx/venv
+	rm -rf reference/commands
 
 clean-doc:
 	git clean -fx "$(BUILDDIR)"

docs/conf.py

@@ -1,3 +1,13 @@
+import datetime
+import os
+import pathlib
+import sys
+
+project_dir = pathlib.Path("..").resolve()
+sys.path.insert(0, str(project_dir.absolute()))
+
+import snapcraft
+
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
@@ -7,11 +17,9 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "Snapcraft"
-copyright = "2023, Canonical"
-author = "Canonical"
-
-# region General configuration
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+author = "Canonical Group Ltd"
+copyright = "%s, %s" % (datetime.date.today().year, author)
+release = snapcraft.__version__
 
 extensions = [
     "sphinx.ext.intersphinx",
@@ -21,8 +29,6 @@
     "sphinx_design",
     "sphinx_copybutton",
     "sphinx-pydantic",
-    "sphinx_toolbox",
-    "sphinx_toolbox.more_autodoc",
     "sphinx.ext.autodoc",  # Must be loaded after more_autodoc
 ]
 
@@ -31,21 +37,19 @@
 
 show_authors = False
 
-# endregion
-# region Options for HTML output
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+rst_epilog = """
+.. include:: /reuse/links.txt
+"""
+
+# Links to ignore when checking links
+linkcheck_ignore = ["http://127.0.0.1:8000"]
 
 html_theme = "furo"
 html_static_path = ["_static"]
 html_css_files = [
     "css/custom.css",
 ]
 
-# endregion
-# region Options for extensions
-# Intersphinx extension
-# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
-
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
 }
@@ -59,4 +63,11 @@
 github_username = "snapcore"
 github_repository = "snapcraft"
 
-# endregion
+
+def generate_cli_docs(nil):
+    gen_cli_docs_path = (project_dir / "tools" / "docs" / "gen_cli_docs.py").resolve()
+    os.system("%s %s" % (gen_cli_docs_path, project_dir / "docs"))
+
+
+def setup(app):
+    app.connect("builder-inited", generate_cli_docs)

docs/reference/commands.rst

@@ -0,0 +1,54 @@
+Snapcraft commands
+==================
+
+.. Use a hidden table of contents to ensure that documentation is read.
+
+.. include:: commands/toc.rst
+
+Lifecycle
+---------
+Lifecycle commands can take an optional parameter ``<part-name>``. When a part
+name is provided, the command applies to the specific part. When no part name is
+provided, the command applies to all parts.
+
+.. include:: commands/lifecycle-commands.rst
+
+Extensions
+----------
+
+.. include:: commands/extensions-commands.rst
+
+Other
+-----
+
+.. include:: commands/other-commands.rst
+
+Store account
+-------------
+
+.. include:: commands/store-account-commands.rst
+
+Store key management
+--------------------
+
+.. include:: commands/store-key-management-commands.rst
+
+Store snap names
+----------------
+
+.. include:: commands/store-snap-names-commands.rst
+
+Store snap release management
+-----------------------------
+
+.. include:: commands/store-snap-release-management-commands.rst
+
+Store snap tracks
+-----------------
+
+.. include:: commands/store-snap-tracks-commands.rst
+
+Store validation sets
+---------------------
+
+.. include:: commands/store-validation-sets-commands.rst

docs/reference/index.rst

@@ -6,6 +6,8 @@ Reference
 .. toctree::
    :maxdepth: 1
 
+   commands
+
 Indices and tables
 ==================
 

docs/requirements.txt

@@ -0,0 +1,47 @@
+attrs==23.1.0
+catkin-pkg==0.5.2
+click==8.1.3
+craft-archives==1.1.0
+craft-cli==2.0.0
+craft-grammar==1.1.1
+craft-parts==1.22.0
+craft-providers==1.13.0
+craft-store==2.4.0
+Deprecated==1.2.13
+distro==1.8.0
+gnupg==2.3.1
+httplib2==0.22.0
+jsonpointer==2.3
+jsonschema==2.5.1
+launchpadlib==1.11.0
+lazr.restfulclient==0.14.5
+lazr.uri==1.0.6
+mypy-extensions==1.0.0
+oauthlib==3.2.2
+overrides==7.3.1
+platformdirs==2.6.0
+polib==1.1.1
+progressbar==2.5
+psutil==5.9.4
+pydantic>=1.9.0
+pydantic-yaml==0.8.1
+pyelftools==0.29
+pylxd==2.3.1
+python-debian==0.1.49
+pyxdg==0.28
+PyYAML==6.0
+raven==6.10.0
+regex==2022.10.31
+requests-unixsocket==0.3.0
+semver==2.13.0
+simplejson==3.19.1
+snap-helpers==0.3.2
+spdx==2.5.1
+spdx-lookup==0.3.3
+tabulate==0.8.10
+types-Deprecated==1.2.9
+typing_extensions
+wadllib==1.3.6
+wrapt==1.14.1
+pyspelling==2.8.2
+python-apt @ https://launchpad.net/ubuntu/+archive/primary/+sourcefiles/python-apt/2.4.0ubuntu1/python-apt_2.4.0ubuntu1.tar.xz; sys.platform == "linux"

docs/reuse/links.txt

@@ -0,0 +1,7 @@
+.. _Canonical website: https://canonical.com/
+.. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/
+.. _Sphinx reStructuredText Primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+.. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en
+.. _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/

extensions/desktop/common/desktop-exports

@@ -1,7 +1,10 @@
 #!/bin/bash
-###############################################
-# Launcher common exports for any desktop app #
-###############################################
+###########################################################
+# Launcher common exports for any desktop app
+# This is not used with the gnome extension for
+# core22 and later, please see
+# https://github.com/snapcore/snapcraft-desktop-integration
+###########################################################
 
 # Note: We avoid using `eval` because we don't want to expand variable names
 #       in paths. For example: LD_LIBRARY_PATH paths might contain `$LIB`.

extensions/desktop/common/fonts

@@ -1,5 +1,11 @@
 #!/bin/bash
 
+###########################################################
+# This is not used with the gnome extension for
+# core22 and later, please see
+# https://github.com/snapcore/snapcraft-desktop-integration
+###########################################################
+
 set -e
 
 [ ! -d "${SNAP_COMMON}/fontconfig" ] && mkdir -p "${SNAP_COMMON}/fontconfig"

extensions/desktop/common/init

@@ -1,7 +1,10 @@
 #!/bin/bash
-#################
-# Launcher init #
-#################
+###########################################################
+# Launcher init
+# This is not used with the gnome extension for
+# core22 and later, please see
+# https://github.com/snapcore/snapcraft-desktop-integration
+###########################################################
 
 # shellcheck disable=SC2034
 START=$(date +%s.%N)

extensions/desktop/common/mark-and-exec

@@ -1,7 +1,10 @@
 #!/bin/bash
-###############################
-# Mark update and exec binary #
-###############################
+###########################################################
+# Mark update and exec binary
+# This is not used with the gnome extension for
+# core22 and later, please see
+# https://github.com/snapcore/snapcraft-desktop-integration
+###########################################################
 
 # shellcheck disable=SC2154
 [ "$needs_update" = true ] && echo "SNAP_DESKTOP_LAST_REVISION=$SNAP_REVISION" > "$SNAP_USER_DATA/.last_revision"

extensions/desktop/gnome/launcher-specific

@@ -1,7 +1,10 @@
 #!/bin/bash
-##############################
-# GTK launcher specific part #
-##############################
+###########################################################
+# GTK launcher specific part
+# This is not used with the gnome extension for
+# core22 and later, please see
+# https://github.com/snapcore/snapcraft-desktop-integration
+###########################################################
 
 # shellcheck disable=SC2154
 if [ "$wayland_available" = true ]; then