canonical · tigarmo · Mar 8, 2024 · Mar 5, 2024 · Mar 5, 2024 · Mar 5, 2024
diff --git a/.gitignore b/.gitignore
@@ -14,6 +14,7 @@ docs/reference.md
 docs/reference/commands
 docs/.sphinx
 docs/_build
+docs/common
 *.egg-info
 .eggs/
 .envrc

diff --git a/docs/common/.gitkeep b/docs/common/.gitkeep
diff --git a/docs/conf.py b/docs/conf.py
@@ -3,6 +3,8 @@
 import pathlib
 import sys
 
+import craft_parts_docs
+
 project_dir = pathlib.Path("..").resolve()
 sys.path.insert(0, str(project_dir.absolute()))
 
@@ -60,7 +62,12 @@
 
 myst_enable_extensions = ["substitution", "deflist"]
 
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "sphinx-resources"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "sphinx-resources",
+]
 
 rst_epilog = """
 .. include:: /reuse/links.txt
@@ -161,6 +168,34 @@
 # For example: "explanation/old-name.html": "../how-to/prettify.html",
 # redirects = {}
 
+extensions.extend(
+    (
+        "sphinx.ext.ifconfig",
+        "sphinxcontrib.details.directive",
+    )
+)
+
+exclude_patterns.extend(
+    (
+        # Excluded because Snapcraft doesn't use overlays
+        "common/craft-parts/overlay_parameters.rst",
+        # Excluded here because they are included explicitly in other documents;
+        # if we don't exclude them, they generate "duplicate label" errors.
+        "common/craft-parts/dump_plugin.rst",
+        "common/craft-parts/part_properties.rst",
+        "common/craft-parts/python_plugin.rst",
+        "common/craft-parts/rust_plugin.rst",
+        "common/craft-parts/step_execution_environment.rst",
+        "common/craft-parts/step_output_directories.rst",
+        "common/craft-parts/explanation/filesets.rst",
+        "common/craft-parts/explanation/lifecycle.rst",
+        "common/craft-parts/explanation/parts.rst",
+        "common/craft-parts/explanation/how_parts_are_built.rst",
+        "common/craft-parts/reference/parts_steps.rst",
+        # Extra non-craft-parts exclusions can be added after this comment
+    )
+)
+
 
 def generate_cli_docs(nil):
     gen_cli_docs_path = (project_dir / "tools" / "docs" / "gen_cli_docs.py").resolve()
@@ -169,3 +204,12 @@ def generate_cli_docs(nil):
 
 def setup(app):
     app.connect("builder-inited", generate_cli_docs)
+
+
+# Setup libraries documentation snippets for use in snapcraft docs.
+common_docs_path = pathlib.Path(__file__).parent / "common"
+craft_parts_docs_path = pathlib.Path(craft_parts_docs.__file__).parent
+(common_docs_path / "craft-parts").unlink(missing_ok=True)
+(common_docs_path / "craft-parts").symlink_to(
+    craft_parts_docs_path, target_is_directory=True
+)
diff --git a/docs/explanation/filesets.rst b/docs/explanation/filesets.rst
@@ -0,0 +1,2 @@
+
+.. include:: /common/craft-parts/explanation/filesets.rst
diff --git a/docs/explanation/how_parts_are_built.rst b/docs/explanation/how_parts_are_built.rst
@@ -0,0 +1,2 @@
+
+.. include:: /common/craft-parts/explanation/how_parts_are_built.rst
diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst
@@ -7,3 +7,6 @@ Explanation
    :maxdepth: 1
 
    architectures
+   filesets
+   parts
+   lifecycle
diff --git a/docs/explanation/lifecycle.rst b/docs/explanation/lifecycle.rst
@@ -0,0 +1,2 @@
+
+.. include:: /common/craft-parts/explanation/lifecycle.rst
diff --git a/docs/explanation/parts.rst b/docs/explanation/parts.rst
@@ -0,0 +1,2 @@
+
+.. include:: /common/craft-parts/explanation/parts.rst
diff --git a/docs/images/lifecycle_logic.png b/docs/images/lifecycle_logic.png
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -8,6 +8,9 @@ Reference
 
    architectures
    commands
+   plugins
+   part_properties
+   parts_steps
 
 Indices and tables
 ==================

diff --git a/docs/reference/part_properties.rst b/docs/reference/part_properties.rst
@@ -0,0 +1,6 @@
+.. _ref_parts:
+
+Part properties
+===============
+
+.. include:: /common/craft-parts/part_properties.rst
diff --git a/docs/reference/parts_steps.rst b/docs/reference/parts_steps.rst
@@ -0,0 +1,6 @@
+
+.. include:: /common/craft-parts/reference/parts_steps.rst
+
+.. include:: /common/craft-parts/step_execution_environment.rst
+
+.. include:: /common/craft-parts/step_output_directories.rst
diff --git a/docs/reference/plugins.rst b/docs/reference/plugins.rst
@@ -0,0 +1,15 @@
+.. _plugins:
+
+*****************
+Snapcraft plugins
+*****************
+
+This section contains an in-depth description of the plugins available in
+Snapcraft.
+
+.. toctree::
+   :maxdepth: 1
+
+   plugins/dump_plugin
+   plugins/python_plugin
+   plugins/rust_plugin
diff --git a/docs/reference/plugins/dump_plugin.rst b/docs/reference/plugins/dump_plugin.rst
@@ -0,0 +1,2 @@
+
+.. include:: /common/craft-parts/dump_plugin.rst
diff --git a/docs/reference/plugins/python_plugin.rst b/docs/reference/plugins/python_plugin.rst
@@ -0,0 +1,23 @@
+
+.. include:: /common/craft-parts/python_plugin.rst
+   :end-before: .. _python-details-begin:
+
+Dependencies
+------------
+
+Whether the Python interpreter needs to be included in the snap depends on its
+``confinement``. Specifically:
+
+- Projects with ``strict`` or ``devmode`` confinement can safely use the base
+  snap's interpreter, so they typically do **not** need to include Python.
+- Projects with ``classic`` confinement **cannot** use the base snap's
+  interpreter and thus must always bundle it (typically via ``stage-packages``).
+- In both cases, a specific/custom Python installation can always be included
+  in the snap. This can be useful, for example, when using a different Python
+  version or building an interpreter with custom flags.
+
+Snapcraft will prefer an included interpreter over the base's, even for projects
+with ``strict`` and ``devmode`` confinement.
+
+.. include:: /common/craft-parts/python_plugin.rst
+   :start-after: .. _python-details-end:
diff --git a/docs/reference/plugins/rust_plugin.rst b/docs/reference/plugins/rust_plugin.rst
@@ -0,0 +1,2 @@
+
+.. include:: /common/craft-parts/rust_plugin.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,10 +1,11 @@
 attrs==23.1.0
 catkin-pkg==0.5.2
 click==8.1.7
+craft-application==1.2.1
 craft-archives==1.1.3
 craft-cli==2.5.1
 craft-grammar==1.1.1
-craft-parts==1.26.2
+craft-parts==1.27.0
 craft-providers==1.23.0
 craft-store==2.5.0
 Deprecated==1.2.14
@@ -40,6 +41,7 @@ simplejson==3.19.2
 snap-helpers==0.4.2
 spdx==2.5.1
 spdx-lookup==0.3.3
+sphinxcontrib-details-directive==0.1.0
 tabulate==0.8.10
 types-Deprecated==1.2.9.2
 typing_extensions==4.5.0

diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt
@@ -1,13 +1,15 @@
 .. _AppStream: https://www.freedesktop.org/software/appstream/docs/
 .. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en
 .. _Canonical website: https://canonical.com/
+.. _`Charmcraft`: https://juju.is/docs/sdk/charmcraft
 .. _`Create a brand account`: https://snapcraft.io/docs/t/creating-snap-store-brand-accounts/6271
 .. _`Kernel connector`: https://www.kernel.org/doc/Documentation/connector/connector.txt
 .. _managing-snap-configuration: https://snapcraft.io/docs/configuration-in-snaps
 .. _`Markdown`: https://commonmark.org/help/
 .. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/
 .. _ROS: https://www.ros.org/
 .. _setuptools: https://setuptools.readthedocs.io/en/latest/
+.. _`Snapcraft`: https://snapcraft.io/docs/snapcraft
 .. _`snap-channels`: https://snapcraft.io/docs/channels
 .. _`Snap Store desktop app`: https://snapcraft.io/snap-store
 .. _`Snap Store`: https://snapcraft.io/store
@@ -16,3 +18,4 @@
 .. _`Ubuntu Core`: https://ubuntu.com/core/
 .. _vscode: https://code.visualstudio.com/
 .. _`YAML specification`: https://yaml.org/spec/
+
diff --git a/requirements-devel.txt b/requirements-devel.txt
@@ -15,7 +15,7 @@ craft-application==1.2.1
 craft-archives==1.1.3
 craft-cli==2.5.1
 craft-grammar==1.1.2
-craft-parts==1.26.2
+craft-parts==1.27.0
 craft-providers==1.23.0
 craft-store==2.6.0
 cryptography==42.0.4

diff --git a/requirements.txt b/requirements.txt
@@ -9,7 +9,7 @@ craft-application==1.2.1
 craft-archives==1.1.3
 craft-cli==2.5.1
 craft-grammar==1.1.2
-craft-parts==1.26.2
+craft-parts==1.27.0
 craft-providers==1.23.0
 craft-store==2.6.0
 cryptography==42.0.4

diff --git a/tox.ini b/tox.ini
@@ -138,7 +138,7 @@ commands_pre =
     mypy: mkdir -p .mypy_cache
 commands =
     pyright: pyright {posargs}
-    mypy: mypy --install-types --non-interactive --exclude 'docs/sphinx-resources/conf.py' .
+    mypy: mypy --install-types --non-interactive --exclude 'docs/sphinx-resources/conf.py' --exclude 'docs/common' .
 
 [testenv:format-{black,ruff,codespell}]
 description = Automatically format source code