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 Snapcraft doc.
ScarlettGatelyMoore · Mar 21, 2024 · b8c9a17 · b8c9a17
1 parent efcff38
commit b8c9a17
Show file tree

Hide file tree

Showing 15 changed files with 27 additions and 41 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,4 +1,5 @@
 import datetime
+import logging
 import os
 import pathlib
 import sys
@@ -179,19 +180,17 @@
     (
         # 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",
+        # 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/overlay_parameters.rst",
+        "common/craft-parts/explanation/overlays.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
     )
 )
@@ -208,7 +207,7 @@ def setup(app):
 
 # 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
+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/filesets.rst b/docs/explanation/filesets.rst
diff --git a/docs/explanation/how_parts_are_built.rst b/docs/explanation/how_parts_are_built.rst
diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst
@@ -7,6 +7,8 @@ Explanation
    :maxdepth: 1
 
    architectures
-   filesets
-   parts
-   lifecycle
+   /common/craft-parts/explanation/filesets
+   /common/craft-parts/explanation/parts
+   /common/craft-parts/explanation/how_parts_are_built
+   /common/craft-parts/explanation/lifecycle
+   /common/craft-parts/explanation/dump_plugin
diff --git a/docs/explanation/lifecycle.rst b/docs/explanation/lifecycle.rst
diff --git a/docs/explanation/parts.rst b/docs/explanation/parts.rst
diff --git a/docs/howto/index.rst b/docs/howto/index.rst
@@ -7,3 +7,5 @@ How-to guides
    :maxdepth: 1
 
    architectures
+   /common/craft-parts/how-to/include_files
+   /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/index.rst b/docs/reference/index.rst
@@ -9,7 +9,7 @@ Reference
    architectures
    commands
    plugins
-   part_properties
+   /common/craft-parts/reference/part_properties
    parts_steps
 
 Indices and tables

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 @@ Snapcraft.
 .. 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
@@ -19,5 +19,5 @@ Whether the Python interpreter needs to be included in the snap depends on its
 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
+.. 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