refactor: address PR reviews about structure

eduNEXT · Sep 30, 2024 · f500ca6 · f500ca6
1 parent 9bc5f99
commit f500ca6
Show file tree

Hide file tree

Showing 12 changed files with 68 additions and 24 deletions.
diff --git a/...how_tos/configuring_docker_registries.rst → ...e/how_tos/configure_docker_registries.rst b/...how_tos/configuring_docker_registries.rst → ...e/how_tos/configure_docker_registries.rst
@@ -1,5 +1,5 @@
-Configuring Docker Registries
-###################################
+Configure a Different Docker Registry
+#####################################
 
 In Tutor, you can configure docker registries by setting the variable ``DOCKER_REGISTRY`` in the ``config.yml`` file. This variable is used to specify the registry where the images will be pushed. By default, the images are pushed to the Docker Hub registry ``docker.io/``.
 

diff --git a/docs/source/how_tos/configurations.rst → docs/source/how_tos/configure_workflow.rst b/docs/source/how_tos/configurations.rst → docs/source/how_tos/configure_workflow.rst
@@ -1,7 +1,7 @@
-Picasso Workflow Configurations
-###################################
+Configure Picasso Workflow
+###########################
 
-Picasso is a `Github Workflow`_ implemented to be flexible enough to be adopted by different organizations with their own requirements. This document will guide you through the different configurations available to you.
+Picasso is a `Github Workflow`_ implemented to be flexible enough to be adopted by different organizations with their own requirements. This document will guide you through the different configurations available to you when using the Picasso workflow in your repository.
 
 .. _`Github Workflow`: https://docs.github.com/en/actions/sharing-automations/reusing-workflows
 

diff --git a/docs/source/how_tos/index.rst b/docs/source/how_tos/index.rst
@@ -0,0 +1,12 @@
+How-to Guides
+#############
+
+This page contains a list of How-tos that will help you get started with Picasso Workflow.
+
+.. toctree::
+   :maxdepth: 2
+
+   configure_workflow
+   reuse_workflow
+   configure_docker_registries
+   trigger_build_with_cli
diff --git a/docs/source/tutorials/reuse_workflow.rst → docs/source/how_tos/reuse_workflow.rst b/docs/source/tutorials/reuse_workflow.rst → docs/source/how_tos/reuse_workflow.rst
@@ -1,5 +1,5 @@
-Reusing the Picasso Workflow
-###################################
+Reuse Picasso Workflow in Your Repository
+##########################################
 
 This document will guide you through different ways of reusing the Picasso workflow in your own repository.
 

diff --git a/...urce/tutorials/trigger_build_with_cli.rst → ...source/how_tos/trigger_build_with_cli.rst b/...urce/tutorials/trigger_build_with_cli.rst → ...source/how_tos/trigger_build_with_cli.rst
@@ -1,5 +1,5 @@
-Trigger a build with the GitHub CLI
-####################################
+Trigger a New Build with the GitHub CLI
+########################################
 
 Consider you're using the Picasso Workflow like in the following snippet to build Open edX images:
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -11,7 +11,5 @@ Here, you will find details on how to use and configure Picasso Workflow in your
     :maxdepth: 2
     :caption: Contents
 
-    quickstart
-    topic-guides/index
-    how-tos/index
-    tutorials/index
+    topic_guides/index
+    how_tos/index
diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
diff --git a/docs/source/topic-guides/index.rst b/docs/source/topic-guides/index.rst
diff --git a/docs/source/topic-guides/picasso_reusable_workflow.rst b/docs/source/topic-guides/picasso_reusable_workflow.rst
diff --git a/docs/source/topic_guides/index.rst b/docs/source/topic_guides/index.rst
@@ -0,0 +1,9 @@
+Topic Guides
+#############
+
+This page contains an overview of the key features of the Picasso Workflow.
+
+.. toctree::
+   :maxdepth: 2
+
+   reusable_build_workflow
diff --git a/docs/source/topic_guides/reusable_build_workflow.rst b/docs/source/topic_guides/reusable_build_workflow.rst
@@ -0,0 +1,36 @@
+Reusable Build Workflow (Picasso)
+##################################
+
+The Picasso Workflow is a `reusable GitHub Actions workflow`_` designed to build Open edX Docker images for Tutor environments. It simplifies the process of building custom Open edX images with additional functionality, making it easier to maintain, extend, and deploy environments using modern CI/CD practices.
+
+Purpose
+=======
+
+Picasso is a tool designed to help teams simplify the build process for the Open edX Docker images, tailored explicitly for use in Tutor environments. It enables the addition of custom behaviors and features through the internal plugin `tutor-contrib-picasso`_, allowing for additional flexibility during the build process.
+
+This GitHub Actions workflow replaces the existing `Jenkins-based pipeline`_ and integrates directly with other workflows, allowing it to be called in custom jobs. Picasso leverages Tutor to build images from the **Olive** version of Open edX onwards. The resulting Docker images can be used for both production and development environments, simplifying the process of managing multiple environments while ensuring consistency.
+
+With Picasso, teams can build custom Open edX images with additional functionality, making it easier to maintain, extend, and deploy environments using modern CI/CD practices.
+
+.. _`Jenkins-based pipeline`: https://github.com/eduNEXT/dedalo-scripts/blob/main/jenkins/picasso_v2
+.. _reusable GitHub Actions workflow: https://docs.github.com/en/actions/sharing-automations/reusing-workflows
+
+Workflow Overview
+=================
+
+The Picasso Workflow is designed to build Open edX Docker images for Tutor environments.
+
+Key features of the Picasso Workflow include:
+
+- **Runs on GitHub-hosted runners**: By default, the workflow uses ``ubuntu-latest`` runners to execute jobs. This can't be changed to self-hosted runners for the time being.
+- **Builds and pushes Docker images**: The workflow pushes images to Dockerhub by default. This can be customized to push images to other registries.
+- **Supports multiple services**: You can specify the service to build (e.g., ``openedx``, ``mfe``, ``codejail``, etc.) using the ``SERVICE`` input.
+- **Customizable repository and strain**: The workflow allows for specifying the repository, branch, and path to the strain being built. This enables building images from different configurations.
+- **Configurable BuildKit parallelism**: By default, the workflow limits parallelism during the build process to optimize resource usage, although this can be changed using the ``ENABLE_LIMIT_BUILDKIT_PARALLELISM`` input. This is useful for low-powered machines, like `Github Actions standard runners`_.
+- **Private repository access**: SSH keys are used to clone private repositories securely. The SSH private key should be stored as a secret in the repository, and must have access to the repository specified in ``STRAIN_REPOSITORY``.
+- **Extra commands**: The workflow allows running additional custom commands with ``tutor picasso run-extra-commands``. For details, refer to the `tutor-contrib-picasso`_ documentation.
+- **Environment setup**: The workflow sets up and configures Tutor Virtual Environments (TVM), installs necessary plugins like ``tutor-contrib-picasso``, and prepares the environment to build and push Docker images using the `Tutor CLI`_.
+
+.. _tutor-contrib-picasso: https://github.com/eduNEXT/tutor-contrib-picasso/
+.. _Github Actions standard runners: https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners
+.. _Tutor CLI: https://docs.tutor.edly.io/
diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst