docs: tutorials->tutorial and rename flask page (#620)

* docs: tutorials->tutorial and rename flask page * fix: Update .github/ISSUE_TEMPLATE/docs.yaml
canonical · Jul 10, 2024 · bc5e0b6 · bc5e0b6
1 parent 1a5740a
commit bc5e0b6
Show file tree

Hide file tree

Showing 32 changed files with 62 additions and 62 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1,5 +1,5 @@
 Rockcraft documentation
-===========================================
+=======================
 
 **Rockcraft is a tool to create** :ref:`rocks <rocks_explanation>` -- a new
 generation of secure, stable and `OCI-compliant container images
@@ -22,15 +22,15 @@ allowing complex operations to be declared at build time.
    :maxdepth: 1
    :hidden:
 
-   tutorials/index
+   tutorial/index
    how-to/index
    reference/index
    explanation/index
 
 
 .. grid:: 1 1 2 2
 
-   .. grid-item-card:: :ref:`Tutorials <tutorials>`
+   .. grid-item-card:: :ref:`Tutorial <tutorial>`
 
       **Get started** - become familiar with Rockcraft by containerising different software applications as rocks.
 

diff --git a/docs/reuse/tutorials/code/task.yaml → docs/reuse/tutorial/code/task.yaml b/docs/reuse/tutorials/code/task.yaml → docs/reuse/tutorial/code/task.yaml
diff --git a/docs/reuse/tutorials/setup.rst → docs/reuse/tutorial/setup.rst b/docs/reuse/tutorials/setup.rst → docs/reuse/tutorial/setup.rst
@@ -42,15 +42,15 @@ 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]
     :dedent: 2
 
 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 → docs/tutorial/chisel.rst b/docs/tutorials/chisel.rst → 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 → docs/tutorial/code/chisel/rockcraft.yaml b/docs/tutorials/code/chisel/rockcraft.yaml → docs/tutorial/code/chisel/rockcraft.yaml
diff --git a/docs/tutorials/code/chisel/task.yaml → docs/tutorial/code/chisel/task.yaml b/docs/tutorials/code/chisel/task.yaml → docs/tutorial/code/chisel/task.yaml
diff --git a/...ls/code/getting-started-with-flask/app.py → docs/tutorial/code/flask/app.py b/...ls/code/getting-started-with-flask/app.py → docs/tutorial/code/flask/app.py
diff --git a/...tting-started-with-flask/requirements.txt → docs/tutorial/code/flask/requirements.txt b/...tting-started-with-flask/requirements.txt → docs/tutorial/code/flask/requirements.txt
diff --git a/...code/getting-started-with-flask/task.yaml → docs/tutorial/code/flask/task.yaml b/...code/getting-started-with-flask/task.yaml → docs/tutorial/code/flask/task.yaml
diff --git a/...de/getting-started-with-flask/time-app.py → docs/tutorial/code/flask/time-app.py b/...de/getting-started-with-flask/time-app.py → docs/tutorial/code/flask/time-app.py
diff --git a/...tutorials/code/hello-world/rockcraft.yaml → .../tutorial/code/hello-world/rockcraft.yaml b/...tutorials/code/hello-world/rockcraft.yaml → .../tutorial/code/hello-world/rockcraft.yaml
diff --git a/docs/tutorials/code/hello-world/task.yaml → docs/tutorial/code/hello-world/task.yaml b/docs/tutorials/code/hello-world/task.yaml → docs/tutorial/code/hello-world/task.yaml
diff --git a/docs/tutorials/code/node-app/rockcraft.yaml → docs/tutorial/code/node-app/rockcraft.yaml b/docs/tutorials/code/node-app/rockcraft.yaml → docs/tutorial/code/node-app/rockcraft.yaml
diff --git a/.../tutorials/code/node-app/src/package.json → docs/tutorial/code/node-app/src/package.json b/.../tutorials/code/node-app/src/package.json → docs/tutorial/code/node-app/src/package.json
diff --git a/docs/tutorials/code/node-app/src/server.js → docs/tutorial/code/node-app/src/server.js b/docs/tutorials/code/node-app/src/server.js → docs/tutorial/code/node-app/src/server.js
diff --git a/docs/tutorials/code/node-app/task.yaml → docs/tutorial/code/node-app/task.yaml b/docs/tutorials/code/node-app/task.yaml → docs/tutorial/code/node-app/task.yaml
diff --git a/...torials/code/pyfiglet/expected_output.txt → ...utorial/code/pyfiglet/expected_output.txt b/...torials/code/pyfiglet/expected_output.txt → ...utorial/code/pyfiglet/expected_output.txt
diff --git a/docs/tutorials/code/pyfiglet/rockcraft.yaml → docs/tutorial/code/pyfiglet/rockcraft.yaml b/docs/tutorials/code/pyfiglet/rockcraft.yaml → docs/tutorial/code/pyfiglet/rockcraft.yaml
diff --git a/docs/tutorials/code/pyfiglet/task.yaml → docs/tutorial/code/pyfiglet/task.yaml b/docs/tutorials/code/pyfiglet/task.yaml → docs/tutorial/code/pyfiglet/task.yaml
diff --git a/.../tutorials/getting-started-with-flask.rst → docs/tutorial/flask.rst b/.../tutorials/getting-started-with-flask.rst → 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 <OCI_image_spec_>`_ 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,15 +137,15 @@ Run the Flask rock with Docker
 You already have the rock as an `OCI <OCI_image_spec_>`_ 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]
     :dedent: 2
 
 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,23 +243,23 @@ 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: [email protected]``:
 
-.. 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]
     :dedent: 2
 
 Pack the rock with the new ``bare`` :ref:`base <bases_explanation>`:
 
-.. 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]
     :dedent: 2
 
 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,15 +271,15 @@ 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]
     :dedent: 2
 
 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,15 +311,15 @@ 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**
 ``rockfile.yaml`` file and change the ``version`` (e.g. to ``0.2``).
 
 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 → docs/tutorial/hello-world.rst b/docs/tutorials/hello-world.rst → 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
 -------------