diff --git a/.github/ISSUE_TEMPLATE/docs.yaml b/.github/ISSUE_TEMPLATE/docs.yaml index 1d3cd015a..48b4a4a3a 100644 --- a/.github/ISSUE_TEMPLATE/docs.yaml +++ b/.github/ISSUE_TEMPLATE/docs.yaml @@ -32,7 +32,7 @@ body: attributes: label: Documentation location description: Location of the corresponding documentation page (e.g., file, section, URL), if applicable - placeholder: ex. https://canonical-rockcraft.readthedocs-hosted.com/en/latest/tutorials/hello-world/ + placeholder: ex. https://documentation.ubuntu.com/rockcraft/stable/tutorial/hello-world/ validations: required: false - type: textarea diff --git a/README.rst b/README.rst index 5e65f75d5..445d1abb7 100644 --- a/README.rst +++ b/README.rst @@ -24,7 +24,7 @@ Install Rockcraft from the Snap Store Documentation ------------- -Documentation on the usage of the tool and tutorials can be found on +Documentation on the usage of the tool and tutorial can be found on https://documentation.ubuntu.com/rockcraft/en/stable/ @@ -72,9 +72,9 @@ a number of integrated tests in :code:`tests/spread` can be run with `Spread`_. $ spread tests/spread # Or run a specific test - $ spread tests/spread/tutorials/basic + $ spread tests/spread/tutorial/basic # Use "-v" for verbose, and "-debug" to get a shell if the test fails - $ spread -v -debug tests/spread/tutorials/basic + $ spread -v -debug tests/spread/tutorial/basic .. _Spread: https://github.com/snapcore/spread .. _general notes: https://github.com/snapcore/snapcraft/blob/main/TESTING.md#spread-tests-for-the-snapcraft-snap diff --git a/docs/how-to/documentation/contribute-docs.rst b/docs/how-to/documentation/contribute-docs.rst index 702ea752c..8061e88e2 100644 --- a/docs/how-to/documentation/contribute-docs.rst +++ b/docs/how-to/documentation/contribute-docs.rst @@ -24,20 +24,20 @@ terminal commands need to provide this information in separate files that can be included in the project's test infrastructure. Categories of the documentation that use code snippets will each have their own -directory with a ``code`` folder within. For example, :file:`tutorials/code` -will hold code for the tutorials. +directory with a ``code`` folder within. For example, :file:`tutorial/code` +will hold code for the tutorial. Each page that provides technical information to the reader in the form of code snippets or commands, such as a tutorial or how-to guide, should have its own folder within the :file:`code` directory and contain a :file:`task.yaml` file for spread tests. -For example, the :file:`tutorials/hello-world.rst` tutorial refers to code -supplied in the :file:`tutorials/code/hello-world/task.yaml` file. Additional +For example, the :file:`tutorial/hello-world.rst` tutorial refers to code +supplied in the :file:`tutorial/code/hello-world/task.yaml` file. Additional YAML_ files can also be included when needed, as shown here: .. code:: text - tutorials + tutorial ├─ hello-world.rst └─ code └─ hello-world diff --git a/docs/how-to/get-started.rst b/docs/how-to/get-started.rst index aef317287..88503cac1 100644 --- a/docs/how-to/get-started.rst +++ b/docs/how-to/get-started.rst @@ -1,7 +1,7 @@ How to get started - quick guide ******************************** -See the :ref:`tutorials` for a full getting started guide. +See the :ref:`tutorial` for a full getting started guide. Getting started --------------- diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index 396418f7a..ee487520a 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -4,7 +4,7 @@ How-to guides ************* If you have a specific goal but are already familiar with Rockcraft, our How-to -guides have more in-depth detail than our tutorials and can be applied to a +guides have more in-depth detail than our tutorial and can be applied to a broader set of applications. They'll help you achieve an end result but may require you to understand and diff --git a/docs/how-to/rocks/migrate-to-chiselled-rock.rst b/docs/how-to/rocks/migrate-to-chiselled-rock.rst index 7a2987919..9fb040c43 100644 --- a/docs/how-to/rocks/migrate-to-chiselled-rock.rst +++ b/docs/how-to/rocks/migrate-to-chiselled-rock.rst @@ -16,7 +16,7 @@ Install Rockcraft Install Rockcraft on your host: -.. literalinclude:: ../../tutorials/code/hello-world/task.yaml +.. literalinclude:: ../../tutorial/code/hello-world/task.yaml :language: bash :start-after: [docs:install-rockcraft] :end-before: [docs:install-rockcraft-end] diff --git a/docs/index.rst b/docs/index.rst index 6a7a22fff..5785a032d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,5 @@ Rockcraft documentation -=========================================== +======================= **Rockcraft is a tool to create** :ref:`rocks ` -- a new generation of secure, stable and `OCI-compliant container images @@ -22,7 +22,7 @@ allowing complex operations to be declared at build time. :maxdepth: 1 :hidden: - tutorials/index + tutorial/index how-to/index reference/index explanation/index @@ -30,7 +30,7 @@ allowing complex operations to be declared at build time. .. grid:: 1 1 2 2 - .. grid-item-card:: :ref:`Tutorials ` + .. grid-item-card:: :ref:`Tutorial ` **Get started** - become familiar with Rockcraft by containerising different software applications as rocks. diff --git a/docs/reuse/tutorials/code/task.yaml b/docs/reuse/tutorial/code/task.yaml similarity index 100% rename from docs/reuse/tutorials/code/task.yaml rename to docs/reuse/tutorial/code/task.yaml diff --git a/docs/reuse/tutorials/setup.rst b/docs/reuse/tutorial/setup.rst similarity index 95% rename from docs/reuse/tutorials/setup.rst rename to docs/reuse/tutorial/setup.rst index 54c25592c..8ec7c5c11 100644 --- a/docs/reuse/tutorials/setup.rst +++ b/docs/reuse/tutorial/setup.rst @@ -42,7 +42,7 @@ and initialised: In order to create the rock, you'll need to install Rockcraft: -.. literalinclude:: /reuse/tutorials/code/task.yaml +.. literalinclude:: /reuse/tutorial/code/task.yaml :language: bash :start-after: [docs:install-rockcraft] :end-before: [docs:install-rockcraft-end] @@ -50,7 +50,7 @@ In order to create the rock, you'll need to install Rockcraft: We'll use Docker to run the rock. You can install it as a ``snap``: -.. literalinclude:: /reuse/tutorials/code/task.yaml +.. literalinclude:: /reuse/tutorial/code/task.yaml :language: bash :start-after: [docs:install-docker] :end-before: [docs:install-docker-end] diff --git a/docs/tutorials/chisel.rst b/docs/tutorial/chisel.rst similarity index 93% rename from docs/tutorials/chisel.rst rename to docs/tutorial/chisel.rst index 7cc1382c2..4975bbeaa 100644 --- a/docs/tutorials/chisel.rst +++ b/docs/tutorial/chisel.rst @@ -3,12 +3,12 @@ Install slices in a rock In this tutorial, you will create a lean hello-world rock that uses chisel slices, and then compare the resulting rock with the one created without slices -in :doc:`/tutorials/hello-world`. +in :doc:`/tutorial/hello-world`. Setup your environment ---------------------- -.. include:: /reuse/tutorials/setup.rst +.. include:: /reuse/tutorial/setup.rst Project setup ------------- @@ -85,4 +85,4 @@ Which should print: hello, world The ``chiselled-hello`` image will have a size of 5.6 MB, which is much less in -size than the 8.8 MB ``hello`` rock created in :doc:`/tutorials/hello-world`. +size than the 8.8 MB ``hello`` rock created in :doc:`/tutorial/hello-world`. diff --git a/docs/tutorials/code/chisel/rockcraft.yaml b/docs/tutorial/code/chisel/rockcraft.yaml similarity index 100% rename from docs/tutorials/code/chisel/rockcraft.yaml rename to docs/tutorial/code/chisel/rockcraft.yaml diff --git a/docs/tutorials/code/chisel/task.yaml b/docs/tutorial/code/chisel/task.yaml similarity index 100% rename from docs/tutorials/code/chisel/task.yaml rename to docs/tutorial/code/chisel/task.yaml diff --git a/docs/tutorials/code/getting-started-with-flask/app.py b/docs/tutorial/code/flask/app.py similarity index 100% rename from docs/tutorials/code/getting-started-with-flask/app.py rename to docs/tutorial/code/flask/app.py diff --git a/docs/tutorials/code/getting-started-with-flask/requirements.txt b/docs/tutorial/code/flask/requirements.txt similarity index 100% rename from docs/tutorials/code/getting-started-with-flask/requirements.txt rename to docs/tutorial/code/flask/requirements.txt diff --git a/docs/tutorials/code/getting-started-with-flask/task.yaml b/docs/tutorial/code/flask/task.yaml similarity index 100% rename from docs/tutorials/code/getting-started-with-flask/task.yaml rename to docs/tutorial/code/flask/task.yaml diff --git a/docs/tutorials/code/getting-started-with-flask/time-app.py b/docs/tutorial/code/flask/time-app.py similarity index 100% rename from docs/tutorials/code/getting-started-with-flask/time-app.py rename to docs/tutorial/code/flask/time-app.py diff --git a/docs/tutorials/code/hello-world/rockcraft.yaml b/docs/tutorial/code/hello-world/rockcraft.yaml similarity index 100% rename from docs/tutorials/code/hello-world/rockcraft.yaml rename to docs/tutorial/code/hello-world/rockcraft.yaml diff --git a/docs/tutorials/code/hello-world/task.yaml b/docs/tutorial/code/hello-world/task.yaml similarity index 100% rename from docs/tutorials/code/hello-world/task.yaml rename to docs/tutorial/code/hello-world/task.yaml diff --git a/docs/tutorials/code/node-app/rockcraft.yaml b/docs/tutorial/code/node-app/rockcraft.yaml similarity index 100% rename from docs/tutorials/code/node-app/rockcraft.yaml rename to docs/tutorial/code/node-app/rockcraft.yaml diff --git a/docs/tutorials/code/node-app/src/package.json b/docs/tutorial/code/node-app/src/package.json similarity index 100% rename from docs/tutorials/code/node-app/src/package.json rename to docs/tutorial/code/node-app/src/package.json diff --git a/docs/tutorials/code/node-app/src/server.js b/docs/tutorial/code/node-app/src/server.js similarity index 100% rename from docs/tutorials/code/node-app/src/server.js rename to docs/tutorial/code/node-app/src/server.js diff --git a/docs/tutorials/code/node-app/task.yaml b/docs/tutorial/code/node-app/task.yaml similarity index 100% rename from docs/tutorials/code/node-app/task.yaml rename to docs/tutorial/code/node-app/task.yaml diff --git a/docs/tutorials/code/pyfiglet/expected_output.txt b/docs/tutorial/code/pyfiglet/expected_output.txt similarity index 100% rename from docs/tutorials/code/pyfiglet/expected_output.txt rename to docs/tutorial/code/pyfiglet/expected_output.txt diff --git a/docs/tutorials/code/pyfiglet/rockcraft.yaml b/docs/tutorial/code/pyfiglet/rockcraft.yaml similarity index 100% rename from docs/tutorials/code/pyfiglet/rockcraft.yaml rename to docs/tutorial/code/pyfiglet/rockcraft.yaml diff --git a/docs/tutorials/code/pyfiglet/task.yaml b/docs/tutorial/code/pyfiglet/task.yaml similarity index 100% rename from docs/tutorials/code/pyfiglet/task.yaml rename to docs/tutorial/code/pyfiglet/task.yaml diff --git a/docs/tutorials/getting-started-with-flask.rst b/docs/tutorial/flask.rst similarity index 86% rename from docs/tutorials/getting-started-with-flask.rst rename to docs/tutorial/flask.rst index 63ab5b9e4..c27974cc1 100644 --- a/docs/tutorials/getting-started-with-flask.rst +++ b/docs/tutorial/flask.rst @@ -10,7 +10,7 @@ containerise it in a rock, using Rockcraft's ``flask-framework`` Setup ===== -.. include:: /reuse/tutorials/setup.rst +.. include:: /reuse/tutorial/setup.rst Finally, create a new directory for this tutorial and go inside it: @@ -28,12 +28,12 @@ this tutorial. Create a ``requirements.txt`` file, copy the following text into it and then save it: -.. literalinclude:: code/getting-started-with-flask/requirements.txt +.. literalinclude:: code/flask/requirements.txt In order to test the Flask application locally (before packing it into a rock), install ``python3-venv`` and create a virtual environment: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:create-venv] :end-before: [docs:create-venv-end] @@ -42,12 +42,12 @@ install ``python3-venv`` and create a virtual environment: In the same directory, copy and save the following into a text file called ``app.py``: -.. literalinclude:: code/getting-started-with-flask/app.py +.. literalinclude:: code/flask/app.py :language: python Run the Flask application to verify that it works: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:run-flask] :end-before: [docs:run-flask-end] @@ -62,7 +62,7 @@ Run the Flask application to verify that it works: Test the Flask application by using ``curl`` to send a request to the root endpoint: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:curl-flask] :end-before: [docs:curl-flask-end] @@ -72,7 +72,7 @@ The Flask application should respond with ``Hello, world!``. The Flask application looks good, so you can stop for now: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:stop-flask] :end-before: [docs:stop-flask-end] @@ -85,7 +85,7 @@ First, you'll need a ``rockcraft.yaml`` file. Rockcraft will automate its creation and tailoring for a Flask application by using the ``flask-framework`` profile: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:create-rockcraft-yaml] :end-before: [docs:create-rockcraft-yaml-end] @@ -103,7 +103,7 @@ architecture, include ``arm64`` in ``platforms``. Pack the rock: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:pack] :end-before: [docs:pack-end] @@ -117,7 +117,7 @@ Once Rockcraft has finished packing the Flask rock, you'll find a new file in your working directory (an `OCI `_ archive) with the ``.rock`` extension: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:ls-rock] :end-before: [docs:ls-rock-end] @@ -137,7 +137,7 @@ Run the Flask rock with Docker You already have the rock as an `OCI `_ archive. Now you'll need to import it into a format that Docker recognises: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:skopeo-copy] :end-before: [docs:skopeo-copy-end] @@ -145,7 +145,7 @@ need to import it into a format that Docker recognises: Check that the image was successfully imported into Docker: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:docker-images] :end-before: [docs:docker-images-end] @@ -167,7 +167,7 @@ size: Now you're finally ready to run the rock and test your containerised Flask application: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: text :start-after: [docs:docker-run] :end-before: [docs:docker-run-end] @@ -176,7 +176,7 @@ application: Use the same ``curl`` command as before to send a request to the Flask application's root endpoint which is running inside the container: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: text :start-after: [docs:curl-flask-rock] :end-before: [docs:curl-flask-rock-end] @@ -190,7 +190,7 @@ View the application logs When deploying your Flask rock, you can always get the application logs via ``pebble``: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: text :start-after: [docs:get-logs] :end-before: [docs:get-logs-end] @@ -223,7 +223,7 @@ Now you have a fully functional rock for you Flask application! This concludes the first part of this tutorial, so you can stop the container and remove the respective image for now: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:stop-docker] :end-before: [docs:stop-docker-end] @@ -243,7 +243,7 @@ The first step towards chiselling your rock is to ensure you are using a In ``rockcraft.yaml``, change the ``base`` to ``bare`` and add ``build-base: ubuntu@22.04``: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:change-base] :end-before: [docs:change-base-end] @@ -251,7 +251,7 @@ In ``rockcraft.yaml``, change the ``base`` to ``bare`` and add Pack the rock with the new ``bare`` :ref:`base `: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:chisel-pack] :end-before: [docs:chisel-pack-end] @@ -259,7 +259,7 @@ Pack the rock with the new ``bare`` :ref:`base `: As before, verify that the new rock was created: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:ls-bare-rock] :end-before: [docs:ls-bare-rock-end] @@ -271,7 +271,7 @@ in size! And that's just because of the simple change of ``base``. And the functionality is still the same. As before, you can confirm this by running the rock with Docker -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: text :start-after: [docs:docker-run-chisel] :end-before: [docs:docker-run-chisel-end] @@ -279,7 +279,7 @@ running the rock with Docker and then using the same ``curl`` request: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: text :start-after: [docs:curl-flask-bare-rock] :end-before: [docs:curl-flask-bare-rock-end] @@ -294,7 +294,7 @@ Cleanup And that's it. You can now stop the container and remove the corresponding image: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:stop-docker-chisel] :end-before: [docs:stop-docker-chisel-end] @@ -311,7 +311,7 @@ you want to add a new ``/time`` endpoint which returns the current time. Start by opening the ``app.py`` file in a text editor and update the code to look like the following: -.. literalinclude:: code/getting-started-with-flask/time-app.py +.. literalinclude:: code/flask/time-app.py :language: python Since you are creating a new version of your application, **open the** @@ -319,7 +319,7 @@ Since you are creating a new version of your application, **open the** Pack and run the rock using similar commands as before: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: text :start-after: [docs:docker-run-update] :end-before: [docs:docker-run-update-end] @@ -332,7 +332,7 @@ Pack and run the rock using similar commands as before: Finally, use ``curl`` to send a request to the ``/time`` endpoint: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: text :start-after: [docs:curl-time] :end-before: [docs:curl-time-end] @@ -346,7 +346,7 @@ Cleanup You can now stop the container and remove the corresponding image: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:stop-docker-updated] :end-before: [docs:stop-docker-updated-end] @@ -360,7 +360,7 @@ You've reached the end of this tutorial. If you'd like to reset your working environment, you can simply run the following: -.. literalinclude:: code/getting-started-with-flask/task.yaml +.. literalinclude:: code/flask/task.yaml :language: bash :start-after: [docs:cleanup] :end-before: [docs:cleanup-end] diff --git a/docs/tutorials/hello-world.rst b/docs/tutorial/hello-world.rst similarity index 98% rename from docs/tutorials/hello-world.rst rename to docs/tutorial/hello-world.rst index 3d77b2a34..e61c38200 100644 --- a/docs/tutorials/hello-world.rst +++ b/docs/tutorial/hello-world.rst @@ -4,7 +4,7 @@ Create a "Hello World" rock Setup your environment ---------------------- -.. include:: /reuse/tutorials/setup.rst +.. include:: /reuse/tutorial/setup.rst Project setup ------------- diff --git a/docs/tutorials/index.rst b/docs/tutorial/index.rst similarity index 59% rename from docs/tutorials/index.rst rename to docs/tutorial/index.rst index 44cf41888..9c12daf78 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorial/index.rst @@ -1,14 +1,14 @@ -.. _tutorials: +.. _tutorial: -Tutorials -********* +Tutorial +******** -If you want to learn the basics from experience, then our tutorials will help +If you want to learn the basics from experience, then our tutorial will help you acquire the necessary competencies from real-life examples with fully reproducible steps. -The first tutorials will familiarise you with the basic operations, tools and -workflows for packing rocks. +The first steps of the tutorial will familiarise you with the basic operations, +tools and workflows for packing rocks. .. toctree:: :maxdepth: 1 @@ -16,7 +16,7 @@ workflows for packing rocks. 1. Create a Hello World rock 2. Install slices in a rock -The next tutorials walk you through examples of transforming applications source +The next steps walk you through examples of transforming applications source code into container applications: .. toctree:: @@ -24,4 +24,4 @@ code into container applications: 3. Containerise a PyPI package 4. Bundle a Node.js app within a rock - 5. Build a rock for a Flask application + 5. Build a rock for a Flask application diff --git a/docs/tutorials/node-app.rst b/docs/tutorial/node-app.rst similarity index 98% rename from docs/tutorials/node-app.rst rename to docs/tutorial/node-app.rst index 02d5e00f1..83c4131ab 100644 --- a/docs/tutorials/node-app.rst +++ b/docs/tutorial/node-app.rst @@ -7,7 +7,7 @@ into a rock. Setup your environment ---------------------- -.. include:: /reuse/tutorials/setup.rst +.. include:: /reuse/tutorial/setup.rst Project setup ------------- diff --git a/docs/tutorials/pypi-package.rst b/docs/tutorial/pypi-package.rst similarity index 97% rename from docs/tutorials/pypi-package.rst rename to docs/tutorial/pypi-package.rst index c12066ad7..d5801de16 100644 --- a/docs/tutorials/pypi-package.rst +++ b/docs/tutorial/pypi-package.rst @@ -16,7 +16,7 @@ By the end of this tutorial you will be able to run pyfiglet via docker: Setup your environment ---------------------- -.. include:: /reuse/tutorials/setup.rst +.. include:: /reuse/tutorial/setup.rst Project setup ------------- diff --git a/pyproject.toml b/pyproject.toml index aab5f5670..3b7d99f7d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -39,7 +39,7 @@ extend-exclude = "docs/sphinx-starter-pack" ignore = [ "docs/sphinx-starter-pack", "docs/how-to/code", - "docs/tutorials/code/getting-started-with-flask", + "docs/tutorial/code/flask", "tests/spread/general/extension-django/example_django" ] diff --git a/spread.yaml b/spread.yaml index 26cb0f234..c04220268 100644 --- a/spread.yaml +++ b/spread.yaml @@ -112,8 +112,8 @@ debug-each: | fi suites: - docs/tutorials/code/: - summary: tests basic tutorials from the docs + docs/tutorial/code/: + summary: tests tutorial from the docs systems: - ubuntu-22.04-64 @@ -127,7 +127,7 @@ suites: systems: - ubuntu-22.04-64 - docs/reuse/tutorials/code/: + docs/reuse/tutorial/code/: summary: tests reusable code from the docs systems: - ubuntu-22.04-64