feat(docs): add craft-parts common documentation (#1939)

This brings in the common documentation sets from craft-parts and adds some of the pages. It mostly exists to enable my next PR, where I'll document the `python` and `poetry` plugins.
canonical · Oct 11, 2024 · 534c028 · 534c028
1 parent 71a2b6c
commit 534c028
Show file tree

Hide file tree

Showing 8 changed files with 162 additions and 2 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -58,6 +58,7 @@
 
 extensions.extend(
     [
+        "sphinx.ext.ifconfig",
         "sphinx.ext.intersphinx",
         "sphinx.ext.viewcode",
         "sphinx.ext.coverage",
@@ -66,15 +67,59 @@
         "sphinx_toolbox",
         "sphinx_toolbox.more_autodoc",
         "sphinx.ext.autodoc",  # Must be loaded after more_autodoc
-        "sphinx_autodoc_typehints",  # must be loaded after napoleon
         "sphinxcontrib.details.directive",
         "sphinx_toolbox.collapse",
         "sphinxcontrib.autodoc_pydantic",
+        "sphinxcontrib.details.directive",
+        "sphinx.ext.napoleon",
+        "sphinx_autodoc_typehints",  # must be loaded after napoleon
     ]
 )
 
 # endregion
 
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "env",
+    "sphinx-starter-pack",
+    # Excluded here because they are either included explicitly in other
+    # documents (so they generate "duplicate label" errors) or they aren't
+    # used in this documentation at all (so they generate "unreferenced"
+    # errors).
+    "common/craft-parts/explanation/lifecycle.rst",
+    "common/craft-parts/explanation/overlay_parameters.rst",
+    "common/craft-parts/explanation/overlays.rst",
+    "common/craft-parts/explanation/parts.rst",
+    "common/craft-parts/explanation/how_parts_are_built.rst",
+    "common/craft-parts/explanation/overlay_step.rst",
+    "common/craft-parts/how-to/craftctl.rst",
+    "common/craft-parts/how-to/include_files.rst",
+    "common/craft-parts/how-to/override_build.rst",
+    "common/craft-parts/reference/partition_specific_output_directory_variables.rst",
+    "common/craft-parts/reference/step_output_directories.rst",
+    "common/craft-parts/reference/plugins/ant_plugin.rst",
+    "common/craft-parts/reference/plugins/autotools_plugin.rst",
+    "common/craft-parts/reference/plugins/cmake_plugin.rst",
+    "common/craft-parts/reference/plugins/dotnet_plugin.rst",
+    "common/craft-parts/reference/plugins/go_plugin.rst",
+    "common/craft-parts/reference/plugins/make_plugin.rst",
+    "common/craft-parts/reference/plugins/maven_plugin.rst",
+    "common/craft-parts/reference/plugins/meson_plugin.rst",
+    "common/craft-parts/reference/plugins/npm_plugin.rst",
+    "common/craft-parts/reference/plugins/poetry_plugin.rst",
+    "common/craft-parts/reference/plugins/python_plugin.rst",
+    "common/craft-parts/reference/plugins/qmake_plugin.rst",
+    "common/craft-parts/reference/plugins/rust_plugin.rst",
+    "common/craft-parts/reference/plugins/scons_plugin.rst",
+    # Extra non-craft-parts exclusions can be added after this comment
+]
+
+rst_epilog = """
+.. include:: /reuse/links.txt
+"""
+
 autodoc_default_options = {"exclude-members": "model_post_init"}
 
 # region Options for extensions
@@ -84,6 +129,7 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "craft-parts": ("https://canonical-craft-parts.readthedocs-hosted.com/en/latest/", None),
+    "rockcraft": ("https://documentation.ubuntu.com/rockcraft/en/stable/", None),
 }
 # See also:
 # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes
@@ -119,3 +165,10 @@ def generate_cli_docs(nil):
 
 def setup(app):
     app.connect("builder-inited", generate_cli_docs)
+
+
+# Setup libraries documentation snippets for use in charmcraft docs.
+common_docs_path = pathlib.Path(__file__).parent / "common"
+craft_parts_docs_path = pathlib.Path(craft_parts_docs.__file__).parent / "craft-parts"
+(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/index.rst b/docs/explanation/index.rst
@@ -9,6 +9,10 @@ explanation is hosted on the `Charm SDK docs <https://juju.is/docs/sdk/explanati
 .. toctree::
    :maxdepth: 1
 
+   /common/craft-parts/explanation/dump_plugin
+   /common/craft-parts/explanation/filesets
+   lifecycle
+
 
 `Charm SDK docs <https://juju.is/docs/sdk/explanation>`_
 ========================================================
diff --git a/docs/explanation/lifecycle.rst b/docs/explanation/lifecycle.rst
@@ -0,0 +1,45 @@
+.. _lifecycle:
+
+*****************
+Lifecycle details
+*****************
+
+Each part is built in :ref:`four separate steps <craft_parts_steps>`, each with
+its own input and output locations:
+
+#. ``PULL`` — The source and external dependencies (such as package
+   dependencies) for the part are retrieved from their stated location and
+   placed into a package cache area.
+#. ``BUILD`` — The part is built according to the particular part plugin and
+   build override.
+#. ``STAGE`` — The specified outputs from the ``BUILD`` step are copied into
+   a unified staging area for all parts.
+#. ``PRIME`` — The specified files are copied from the staging area to the
+   priming area for use in the final payload. This is distinct from ``STAGE``
+   in that the ``STAGE`` step allows files that are used in the ``BUILD`` steps
+   of dependent parts to be accessed, while the ``PRIME`` step occurs after all
+   parts have been staged.
+
+.. note::
+   While craft-parts offers an ``OVERLAY`` step as well, charmcraft does not use it.
+   This is a distinction between how Charmcraft and `Rockcraft`_ work.
+
+Step order
+----------
+
+While each part's steps are guaranteed to run in the order above, they are
+not necessarily run immediately following each other, especially if multiple
+parts are included in a project. While specifics are implementation-dependent,
+the general rules for combining parts are:
+
+#. ``PULL`` all parts before running further steps.
+#. ``BUILD`` any unbuilt parts whose dependencies have been staged. If a part
+   has no dependencies, this part is built in the first iteration.
+#. ``STAGE`` any newly-built parts.
+#. Repeat the ``BUILD`` and ``STAGE`` steps until all parts have been staged.
+#. ``PRIME`` all parts.
+
+Further Information
+-------------------
+
+Further information can be found in the `Craft-parts`_ documentation.
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -12,4 +12,6 @@ data can be found in the `Charm SDK docs <https://juju.is/docs/sdk/reference>`_.
 
     commands
     models/index
+    parts
+    plugins/index
     changelog
diff --git a/docs/reference/parts.rst b/docs/reference/parts.rst
@@ -0,0 +1,14 @@
+.. _parts:
+
+Parts
+*****
+
+Parts, powered by :external+craft-parts:ref:`craft-parts <reference>`, power the build
+system that charmcraft uses.
+
+.. toctree::
+   :maxdepth: 1
+
+   /common/craft-parts/reference/part_properties
+   /common/craft-parts/reference/parts_steps
+   /common/craft-parts/reference/step_execution_environment
diff --git a/docs/reference/plugins/index.rst b/docs/reference/plugins/index.rst
@@ -0,0 +1,25 @@
+.. _plugins:
+
+Parts plugins
+*************
+
+Most charms only need one, maybe two parts, typically consisting of one of Charmcraft's
+application-specific plugins such as the `charm plugin`_ or the `reactive plugin`_ and
+potentially the addition of further files using the :ref:`craft_parts_dump_plugin`.
+
+.. toctree::
+    :maxdepth: 1
+
+    /common/craft-parts/reference/plugins/dump_plugin
+    /common/craft-parts/reference/plugins/nil_plugin
+
+.. warning::
+   Other plugins are available from :external+craft-parts:ref:`craft-parts <plugins>`,
+   but these are unsupported in Charmcraft and should be used with caution.
+
+   These plugins may significantly increase the size of a packed charm, and they may
+   not work as intended. Please file a `feature request`_ in Charmcraft if you have a
+   use case for another craft-parts upstream plugin.
+
+.. _charm plugin: https://juju.is/docs/sdk/charmcraft-yaml#heading--the-charm-plugin
+.. _reactive plugin: https://juju.is/docs/sdk/charmcraft-yaml#heading--the-reactive-plugin
diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt
@@ -0,0 +1,17 @@
+.. _Charmcraft: https://canonical-charmcraft.readthedocs-hosted.com
+.. _Chisel: https://github.com/canonical/chisel
+.. _`Chisel releases`: https://github.com/canonical/chisel-releases
+.. _`Craft-parts`: https://canonical-craft-parts.readthedocs-hosted.com
+.. _Docker: https://docs.docker.com/
+.. _`feature request`: https://github.com/canonical/charmcraft/issues/new?assignees=&labels=Enhancement&projects=&template=task.yaml
+.. _`OCI archive format`: https://github.com/opencontainers/image-spec/blob/main/layer.md#distributable-format
+.. _OCI_image_spec: https://github.com/opencontainers/image-spec/blob/main/spec.md
+.. _`OCI layers`: https://github.com/opencontainers/image-spec/blob/main/layer.md
+.. _LXD: https://canonical.com/lxd
+.. _Multipass: https://multipass.run/docs
+.. _`Open Container Initiative`: https://opencontainers.org/
+.. _Rockcraft: https://documentation.ubuntu.com/rockcraft/
+.. _skopeo: https://github.com/containers/skopeo
+.. _Snapcraft: https://snapcraft.io/docs/snapcraft-overview
+
+.. Potentially use a glossary to create indirect references to explanations.
diff --git a/pyproject.toml b/pyproject.toml
@@ -80,7 +80,7 @@ apt = [
     "python-apt>=2.4.0;sys_platform=='linux'"
 ]
 docs = [
-    "canonical-sphinx~=0.1",
+    "canonical-sphinx[full]~=0.2",
     "pyspelling",
     "autodoc-pydantic~=2.0",
     "sphinx-autobuild~=2024.2",