refactor(docs): use more docs from craft-parts

Now that the structure of the shared craft-parts docs has more content, we can simplify our own docs and just use craft-parts' directly in many places. The guideline is this: If the document will be used wholesale, just reference it directly in the TOC. Otherwise, `include` it in a Rockcraft doc.
canonical · Mar 21, 2024 · 5c2263f · 5c2263f
1 parent c6efaa7
commit 5c2263f
Show file tree

Hide file tree

Showing 14 changed files with 30 additions and 34 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -230,21 +230,23 @@
 
 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",
+        # 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/filesets.rst",
         "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/reference/parts_steps.rst",
+        "common/craft-parts/reference/step_execution_environment.rst",
+        "common/craft-parts/reference/step_output_directories.rst",
+        "common/craft-parts/reference/plugins/python_plugin.rst",
+        # Extra non-craft-parts exclusions can be added after this comment
     )
 )
 
@@ -260,7 +262,7 @@ def setup(app):
 
 # Setup libraries documentation snippets for use in rockcraft docs.
 common_docs_path = pathlib.Path(__file__).parent / "common"
-craft_parts_docs_path = pathlib.Path(craft_parts_docs.__file__).parent
+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
@@ -19,3 +19,4 @@ the motivations behind its development.
    filesets
    parts
    lifecycle
+   /common/craft-parts/explanation/dump_plugin
diff --git a/docs/explanation/overlay-step.rst b/docs/explanation/overlay-step.rst
@@ -6,7 +6,7 @@ five separate steps: pull, overlay, build, stage and prime.
 
 The overlay step is specific to rocks and is configured with overlay parameters.
 To learn more about pull, build, stage and prime see
-:doc:`/reference/part_properties`
+:doc:`/common/craft-parts/reference/part_properties`
 
 The overlay step provides the means to modify the base filesystem before the
 build step is applied. If ``overlay-packages`` is used, those packages will be
@@ -16,4 +16,4 @@ environment variable. ``overlay`` can be used to specify which files will be
 migrated to the next steps, and when omitted its default value will be ``"*"``.
 
 .. Include a section about overlay parameters from the Craft Parts documentation.
-.. include:: /common/craft-parts/overlay_parameters.rst
+.. include:: /common/craft-parts/explanation/overlay_parameters.rst
diff --git a/docs/how-to/rocks/index.rst b/docs/how-to/rocks/index.rst
@@ -5,6 +5,8 @@
 
    Use Rockcraft's GitHub Action <rockcraft-pack-action>
    Convert an entrypoint to a Pebble layer <convert-to-pebble-layer>
-   Publish a rock to a registry <publish-a-rock.rst>
-   Migrate a Docker image to a chiselled rock <migrate-to-chiselled-rock.rst>
-   Use the flask extension <use-flask-extension.rst>
+   Publish a rock to a registry <publish-a-rock>
+   Migrate a Docker image to a chiselled rock <migrate-to-chiselled-rock>
+   Use the flask extension <use-flask-extension>
+   Include local and remote files </common/craft-parts/how-to/include_files>
+   Override a plugin's build </common/craft-parts/how-to/override_build>
diff --git a/docs/images/lifecycle_logic.png b/docs/images/lifecycle_logic.png
diff --git a/docs/reference/part_properties.rst b/docs/reference/part_properties.rst
diff --git a/docs/reference/parts_steps.rst b/docs/reference/parts_steps.rst
@@ -1,6 +1,6 @@
 
 .. include:: /common/craft-parts/reference/parts_steps.rst
 
-.. include:: /common/craft-parts/step_execution_environment.rst
+.. include:: /common/craft-parts/reference/step_execution_environment.rst
 
-.. include:: /common/craft-parts/step_output_directories.rst
+.. include:: /common/craft-parts/reference/step_output_directories.rst
diff --git a/docs/reference/plugins.rst b/docs/reference/plugins.rst
@@ -10,6 +10,7 @@ Rockcraft.
 .. toctree::
    :maxdepth: 1
 
-   plugins/dump_plugin
+   /common/craft-parts/reference/plugins/dump_plugin
+   /common/craft-parts/reference/plugins/maven_plugin
    plugins/python_plugin
-   plugins/rust_plugin
+   /common/craft-parts/reference/plugins/rust_plugin
diff --git a/docs/reference/plugins/dump_plugin.rst b/docs/reference/plugins/dump_plugin.rst
diff --git a/docs/reference/plugins/python_plugin.rst b/docs/reference/plugins/python_plugin.rst
@@ -1,5 +1,5 @@
 
-.. include:: /common/craft-parts/python_plugin.rst
+.. include:: /common/craft-parts/reference/plugins/python_plugin.rst
    :end-before: .. _python-details-begin:
 
 Dependencies
@@ -29,5 +29,5 @@ here's an example that uses ``python3.12-venv`` from the Deadsnakes ppa:
        source: .
        stage-packages: [python3.12-venv]
 
-.. include:: /common/craft-parts/python_plugin.rst
+.. include:: /common/craft-parts/reference/plugins/python_plugin.rst
    :start-after: .. _python-details-end:
diff --git a/docs/reference/plugins/rust_plugin.rst b/docs/reference/plugins/rust_plugin.rst
diff --git a/docs/reference/rock_parts/toc.rst b/docs/reference/rock_parts/toc.rst
@@ -1,4 +1,4 @@
 .. toctree::
    :hidden:
 
-   /reference/part_properties
+   /common/craft-parts/reference/part_properties
diff --git a/docs/reference/rockcraft.yaml.rst b/docs/reference/rockcraft.yaml.rst
@@ -240,7 +240,7 @@ is a valid, supported architecture name.
 **Required**: Yes
 
 The set of parts that compose the rock's contents
-(see :ref:`Parts <ref_parts>`).
+(see :ref:`Parts <part_properties>`).
 
 
 .. note::

diff --git a/docs/tutorials/hello-world.rst b/docs/tutorials/hello-world.rst
@@ -32,7 +32,7 @@ save it as ``rockcraft.yaml``:
 
 This file instructs Rockcraft to build a rock that **only** has the ``hello``
 package (and its dependencies) inside. For more information about the ``parts``
-section, check :ref:`ref_parts`. The remaining YAML fields correspond to
+section, check :ref:`part_properties`. The remaining YAML fields correspond to
 metadata that help define and describe the rock. For more information about all
 available fields check :doc:`/reference/rockcraft.yaml`.