Skip to content

docs: add a preview page for reusing packages #929

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
lengau wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

docs: add a preview page for reusing packages #929

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
efe8f6a
docs: add a preview page for reusing packages
lengau Oct 1, 2025
e26ded6
fix: put the tip after the title
lengau Oct 1, 2025
20e2ab3
fix: remove unused replacements
lengau Oct 1, 2025
05bbfd6
fix: add commit link
lengau Oct 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,10 +47,8 @@
"base",
"sphinx-resources",
"common/README.md",
"common/craft-application/how-to-guides/build-remotely.rst",
"common/craft-application/how-to-guides/reuse-packages-between-builds.rst",
"common/craft-application/reference/remote-builds.rst",
"common/craft-application/reference/fetch-service.rst",
# Exclude all of our common docs as they'll be included explicitly.
"common/craft-application/**",
# There's no tutorials right now, so just hide the scaffolding
"tutorials",
]
Expand Down
1 change: 1 addition & 0 deletions docs/how-to-guides/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,4 @@ How-to guides
build-remotely
partitions
platforms
reuse-packages-between-builds
19 changes: 19 additions & 0 deletions docs/how-to-guides/reuse-packages-between-builds.rst
View file
Open in desktop
Copy link
Collaborator Author

@lengau lengau Oct 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rendered: https://canonical-craft-application--929.com.readthedocs.build/en/929/how-to-guides/reuse-packages-between-builds/

Copy link
Contributor

@medubelko medubelko Oct 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't in line with what we want from a page of documentation.

I left it out of Craft Application because I didn't think the generic page would be of use to Craft Application readers. Do you want to include it instead?

Copy link
Collaborator Author

@lengau lengau Oct 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would definitely like it to be available in the docs so people can see what would look like in their app's docs (and make it more discoverable for app docs).

Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
Reuse packages between builds
=============================

.. tip::

This is a preview of the reusable *Reuse packages between builds* documentation.
It can be included in your documentation by inserting a file that looks as follows,
with the appropriate changes

.. literalinclude:: reuse-packages-between-builds.rst
:end-before: :start-after: =====
:start-after: .. :docs-include:
Copy link
Collaborator Author

@lengau lengau Oct 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is no blank line here because otherwise the blank line would be included in the self-referential literalinclude.

.. |an-artifact| replace:: an artifact
.. |app| replace:: <your-app>
.. |app-command| replace:: <craft-app>
.. |artifact| replace:: artifact

.. include:: /common/craft-application/how-to-guides/reuse-packages-between-builds.rst
:start-after: =====
7 changes: 5 additions & 2 deletions docs/reference/changelog.rst
View file
Open in desktop
Copy link
Collaborator Author

@lengau lengau Oct 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rendered: https://canonical-craft-application--929.com.readthedocs.build/en/929/reference/changelog/

Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,15 @@
Changelog
*********

5.11.0 (2025-09-XX)
5.11.0 (2025-10-01)
-------------------

Documentation
=============

- Add common page *Reuse packages between builds* for use in apps' documentation.
- Add common page :doc:`/how-to-guides/reuse-packages-between-builds` for use in apps' documentation.

For a complete list of commits, check out the `5.11.0`_ release on GitHub.

5.10.3 (2025-09-22)
-------------------
Expand Down Expand Up @@ -1062,3 +1064,4 @@ For a complete list of commits, check out the `2.7.0`_ release on GitHub.
.. _5.9.1: https://github.com/canonical/craft-application/releases/tag/5.9.1
.. _5.10.0: https://github.com/canonical/craft-application/releases/tag/5.10.0
.. _5.10.1: https://github.com/canonical/craft-application/releases/tag/5.10.1
.. _5.11.0: https://github.com/canonical/craft-application/releases/tag/5.11.0