Merge branch 'main' into ROCKS-987/docs-live-improvements

canonical · Mar 11, 2024 · 3766d05 · 3766d05
2 parents 683af29 + 1356972
commit 3766d05
Show file tree

Hide file tree

Showing 18 changed files with 103 additions and 17 deletions.
diff --git a/docs/.wordlist.txt b/docs/.wordlist.txt
@@ -11,9 +11,12 @@ cmake
 CMake
 CMD
 CTRL
+dataset
+Deadsnakes
 declaratively
 dev
 Diátaxis
+dir
 distroless
 dnf
 Dockerfile
@@ -26,6 +29,9 @@ entrypoint
 entrypoints
 executables
 expressjs
+Filesets
+fileset
+filesets
 filesystem
 filesystems
 fs
@@ -34,6 +40,7 @@ GiB
 GID
 github
 GPG
+gzipped
 hardcoded
 html
 https
@@ -43,6 +50,8 @@ io
 js
 json
 Kubernetes
+LDFLAGS
+ldflags
 libc
 libssl
 lifecycle
@@ -69,10 +78,13 @@ openssl
 OpenSSL
 OpenSSL's
 organize
+os
 packageName
 Permalink
 PID
 Podman
+ppa
+pre
 pyfiglet
 PyPI
 reStructuredText
@@ -86,8 +98,12 @@ runit
 runtime
 Runtime
 rustc
+RUSTFLAGS
 scons
 SCons
+scriptlets
+SDK
+SDL
 setuptools
 skopeo
 Skopeo
@@ -99,9 +115,12 @@ Snyk's
 SPDX
 SSL
 subdir
+subdirectories
 subdirectory
+subkey
 submodules
 subreaping
+subtree
 supervisord
 symlink
 symlinks
@@ -110,6 +129,7 @@ toml
 toolchain
 triaged
 ubuntu
+unbuilt
 usrmerge
 UID
 venv

diff --git a/docs/conf.py b/docs/conf.py
@@ -103,7 +103,6 @@
     ".DS_Store",
     "env",
     "sphinx-starter-pack",
-    "common",
 ]
 
 # Links to ignore when checking links
@@ -226,6 +225,28 @@
 # Enable support for google-style instance attributes.
 napoleon_use_ivar = True
 
+extensions.extend(("sphinxcontrib.details.directive",))
+
+exclude_patterns.extend(
+    (
+        # 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/overlay_parameters.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/explanation/overlay_step.rst",
+        "common/craft-parts/reference/parts_steps.rst",
+    )
+)
+
 
 def generate_cli_docs(nil):
     gen_cli_docs_path = (project_dir / "tools" / "docs" / "gen_cli_docs.py").resolve()

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
@@ -16,3 +16,6 @@ the motivations behind its development.
    rocks
    pebble
    lifecycle-layer
+   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
@@ -13,3 +13,4 @@ Rockcraft's components, commands and keywords.
    rockcraft.yaml
    commands
    plugins
+   parts_steps
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
@@ -10,5 +10,6 @@ Rockcraft.
 .. 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
@@ -1,2 +1,33 @@
 
 .. include:: /common/craft-parts/python_plugin.rst
+   :end-before: .. _python-details-begin:
+
+Dependencies
+------------
+
+Since none of the bases that are available for rocks contain a default Python
+installation, including a Python interpreter in Rockcraft projects is mandatory.
+The plugin also requires the ``venv`` module to create the virtual environment
+where Python packages are installed at build time.
+
+The easiest way to do this is to include the ``python3-venv`` package in the
+``stage-packages`` of the part that uses the Python plugin. This will pull in
+the default Python interpreter for the ``build-base``, like Python 3.10 for
+Ubuntu 22.04. However, other versions can be used by explicitly declaring them -
+here's an example that uses ``python3.12-venv`` from the Deadsnakes ppa:
+
+.. code-block:: yaml
+
+   package-repositories:
+     - type: apt
+       ppa: deadsnakes/ppa
+       priority: always
+
+   parts:
+     my-part:
+       plugin: python
+       source: .
+       stage-packages: [python3.12-venv]
+
+.. include:: /common/craft-parts/python_plugin.rst
+   :start-after: .. _python-details-end:
diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -17,7 +17,7 @@ coverage==7.4.1
 craft-application==1.2.1
 craft-archives==1.1.3
 craft-cli==2.5.1
-craft-parts==1.26.1
+craft-parts==1.27.0
 craft-providers==1.23.0
 cryptography==42.0.2
 Deprecated==1.2.14

diff --git a/requirements-doc.txt b/requirements-doc.txt
@@ -8,7 +8,7 @@ colorama==0.4.6
 craft-application==1.2.1
 craft-archives==1.1.3
 craft-cli==2.5.1
-craft-parts==1.26.1
+craft-parts==1.27.0
 craft-providers==1.23.0
 Deprecated==1.2.14
 distro==1.9.0
@@ -59,6 +59,7 @@ sphinx-pydantic==0.1.1
 sphinx-rtd-theme==2.0.0
 sphinx_design==0.5.0
 sphinxcontrib-applehelp==1.0.8
+sphinxcontrib-details-directive==0.1.0
 sphinxcontrib-devhelp==1.0.6
 sphinxcontrib-htmlhelp==2.0.5
 sphinxcontrib-jquery==4.1

diff --git a/requirements.txt b/requirements.txt
@@ -3,7 +3,7 @@ charset-normalizer==3.3.2
 craft-application==1.2.1
 craft-archives==1.1.3
 craft-cli==2.5.1
-craft-parts==1.26.1
+craft-parts==1.27.0
 craft-providers==1.23.0
 Deprecated==1.2.14
 distro==1.9.0

diff --git a/schema/rockcraft.json b/schema/rockcraft.json
@@ -554,37 +554,27 @@
         },
         "organize": {
           "title": "Organize",
-          "default": {},
           "type": "object",
           "additionalProperties": {
             "type": "string"
           }
         },
         "overlay": {
           "title": "Overlay",
-          "default": [
-            "*"
-          ],
           "type": "array",
           "items": {
             "type": "string"
           }
         },
         "stage": {
           "title": "Stage",
-          "default": [
-            "*"
-          ],
           "type": "array",
           "items": {
             "type": "string"
           }
         },
         "prime": {
           "title": "Prime",
-          "default": [
-            "*"
-          ],
           "type": "array",
           "items": {
             "type": "string"

diff --git a/tox.ini b/tox.ini
@@ -25,7 +25,9 @@ set_env =
     COVERAGE_FILE={env_tmp_dir}/.coverage_{env_name}
 
 [docs]  # Sphinx documentation configuration
-deps = -r requirements-jammy.txt
+deps =
+  -r requirements-jammy.txt
+  -r requirements-doc.txt
 extras = doc
 package = editable
 no_package = true
@@ -46,12 +48,12 @@ commands = pip install -e {posargs}
 description = Build sphinx documentation
 base = docs
 # "-W" is to treat warnings as errors
-commands = sphinx-build {posargs:-b html} {tox_root}/docs {tox_root}/docs/_build
+commands = sphinx-build -W {posargs:-b html} {tox_root}/docs {tox_root}/docs/_build
 
 [testenv:autobuild-docs]
 description = Build documentation with an autoupdating server
 base = docs
-commands = sphinx-autobuild {posargs:-b html --open-browser --port 8080} --watch {tox_root}/rockcraft {tox_root}/docs {tox_root}/docs/_build
+commands = sphinx-autobuild {posargs: -W -b html --open-browser --port 8080} --watch {tox_root}/rockcraft {tox_root}/docs {tox_root}/docs/_build
 
 [testenv:lint-docs]
 description = Lint the documentation with sphinx-lint
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@

		.. include:: /common/craft-parts/explanation/filesets.rst
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@

		.. include:: /common/craft-parts/dump_plugin.rst