docs: improve documentation (#76)

* docs: fix font-family loading style * docs: enhance plugin documentation according with current tutor version * docs: add indentation to code in list * docs: add badges status
eduNEXT · Aug 2, 2024 · 6e2b263 · 6e2b263
1 parent 4203f47
commit 6e2b263
Show file tree

Hide file tree

Showing 8 changed files with 52 additions and 45 deletions.
diff --git a/README.md b/README.md
@@ -1,11 +1,16 @@
 # TVM
 
+![Maintainance Badge](https://img.shields.io/badge/Status-Maintained-brightgreen)
+![Test Badge](https://img.shields.io/github/actions/workflow/status/edunext/tvm/.github%2Fworkflows%2Ftests.yml?label=Test)
+![GitHub Tag](https://img.shields.io/github/v/tag/edunext/tvm?label=Tag)
+
+
 TVM is a tool that allows you to manage several Tutor development environments so that they work in isolation, and you can work on different projects with independent Tutor versions and configurations.
 
 TVM is also the acronym for:
 
-- Tutor Version Manager: manages the version of Tutor.
-- Tutor enVironment Manager: for creating project-based environments with Tutor.
+- **Tutor Version Manager:** Handle the Tutor versions.
+- **Tutor enVironment Manager:** Create project-based environments with Tutor.
 
 # Installing TVM
 
@@ -27,39 +32,42 @@ Create and activate a new project with the following steps:
 
 1. Install the version of Tutor you want to use with TVM.
 
-```bash
-tvm install <tutor-version>
+   ```bash
+   tvm install <tutor-version>
 
-# For example:
-# tvm install v14.0.0
-```
+   # For example:
+   # tvm install v14.0.0
+   ```
 
 2. Create a new project with TVM.
 
-```bash
-tvm project init <project-name> <tutor-version>
+   ```bash
+   tvm project init <project-name> <tutor-version>
 
-# For example:
-# tvm project init tvm-test v14.0.0
-```
+   # For example:
+   # tvm project init tvm-test v14.0.0
+   ```
 
 3. Open the project folder.
 
-```bash
-cd <project-name>
-```
+   ```bash
+   cd <project-name>
+   ```
 
 4. Activate the project environment.
 
-```bash
-source .tvm/bin/activate
-```
+   ```bash
+   source .tvm/bin/activate
+   ```
 
 5. Run your project.
 
-```bash
-tutor local quickstart
-```
+   ```bash
+   tutor local launch
+   ```
+
+> [!NOTE]
+> For Tutor versions <15, init a project with `tutor local quickstart`
 
 You can start configuring and using your Tutor instance.
 

diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css
@@ -1,12 +1,9 @@
-@font-face {
-font-family: "PoppinsRegular";
-src: url("https://energiasrenovables.edunext.io/asset-v1:energiasrenovables+er01+2022_T1+type@[email protected]") format('truetype');
-}
+@import url('https://fonts.googleapis.com/css2?family=Poppins&display=swap');
 
 
 body {
   padding-top: 0!important;
-  font-family: "PoppinsRegular", serif;
+  font-family: "Poppins", sans-serif;
   width: 112% !important;
 }
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,7 +1,7 @@
 TVM
 ####
 
-TVM is a tool that allows you to manage several Tutor development environments so that they work in isolation, and you can work on different projects with independent Tutor versions and configurations.
+TVM is a tool that allows you to manage several Tutor development environments so that they work in isolation, and you can work on different projects with independent Tutor version and configurations.
 
 User Guide
 -----------
@@ -17,7 +17,7 @@ User Guide
 Releases
 ---------
 
-The Releases are listed on the `Github release page <https://github.com/eduNEXT/tvm/releases>`_. And all notable changes to this project are documented in the `CHANGELOG <https://github.com/eduNEXT/tvm/blob/main/CHANGELOG.md>`_ file.
+The Releases are listed on the `Github release page <https://github.com/eduNEXT/tvm/releases>`_. All notable changes to this project are documented in the `CHANGELOG <https://github.com/eduNEXT/tvm/blob/main/CHANGELOG.md>`_ file.
 
 Source code
 -----------
@@ -27,7 +27,7 @@ The complete source code for TVM is available on Github: https://github.com/eduN
 Support
 --------
 
-To get support, go to the TVM Github discussion forum: https://github.com/eduNEXT/tvm/discussions
+Get support in the TVM Github discussion forum: https://github.com/eduNEXT/tvm/discussions
 
 Contributing
 -------------

diff --git a/docs/source/tvm_advanced_information.rst b/docs/source/tvm_advanced_information.rst
@@ -3,7 +3,7 @@ Advanced Information
 
 TVM is the acronym for:
 
-- Tutor Version Manager: manages the version of Tutor.
-- Tutor enVironment Manager: for creating project-based environments with Tutor.
+- Tutor Version Manager: handles the version of Tutor.
+- Tutor enVironment Manager: creates project-based environments with Tutor.
 
 To develop this tool, we separate the code into two apps accord the two meanings of TVM, and we use a `Hexagonal Architecture <https://en.wikipedia.org/wiki/Hexagonal_architecture_(software)>`_.
diff --git a/docs/source/tvm_quickstart.rst b/docs/source/tvm_quickstart.rst
@@ -17,8 +17,8 @@ TVM works with Tutor for that reason the Tutor requirements are also the TVM req
 **Basic Requirements:**
 
 - Software:
-    - `Docker <https://docs.docker.com/engine/installation/>`_: v18.06.0+
-    - `Docker Compose <https://docs.docker.com/compose/install/>`_: v1.22.0+
+    - `Docker <https://docs.docker.com/engine/installation/>`_: v24.0.5+ (with BuildKit 0.11+)
+    - `Docker Compose <https://docs.docker.com/compose/install/>`_: v2.0.0+
 - Hardware:
     - Minimum configuration: 4 GB RAM, 2 CPU, 8 GB disk space
     - Recommended configuration: 8 GB RAM, 4 CPU, 25 GB disk space
@@ -66,7 +66,9 @@ Step by Step
 
     .. code-block:: bash
 
-        tutor local quickstart
+        tutor local launch
+        
+.. note:: For Tutor versions <15, init a project with ``tutor local quickstart```
 
 
 Next Steps

diff --git a/docs/source/tvm_topic_guides/environment_manager.rst b/docs/source/tvm_topic_guides/environment_manager.rst
@@ -38,7 +38,7 @@ Remove a Project Environment
     # tvm project remove v14.0.0@tvm-test
 
 
-.. note:: You can use the flag --prune to remove all the project folder. Ex: `tvm project remove v14.0.0@tvm-test --prune`
+.. note:: You can use the flag --prune to remove all the project folder. E.g. ``tvm project remove v14.0.0@tvm-test --prune``
 
 
 Activate a Project Environment
@@ -57,7 +57,7 @@ Deactivate a Project Environment
     tvmoff
 
 
-.. warning:: If you also have another environment like a python virtual environment, you need to deactivate each virtual environment in order. For example, if you have `(venv) [v12.2.0@project-name]`, you need to run `deactivate` and then `tvmoff`.
+.. warning:: If you also have another environment like a python virtual environment, you need to deactivate each virtual environment in order. For example, if you have ``(venv) [v12.2.0@project-name]``, you need to run ``deactivate`` and then ``tvmoff``.
 
 List Environments and Projects
 --------------------------------
@@ -67,7 +67,7 @@ List Environments and Projects
     tvm list
 
 
-.. note:: You can use the flag -l or --limit and an integer to limit the output. Ex: `tvm list --limit 10`
+.. note:: You can use the flag -l or --limit and an integer to restrict the output. E.g. ``tvm list --limit 10``
 
 Install Tutor Plugins
 ----------------------
@@ -90,7 +90,7 @@ Pip
     pip install <plugin>
 
 
-.. note:: If you don't already have your project environment activated, you can activate it using `source .tvm/bin/activate`, and then you will be able to use the pip command.
+.. note:: If you don't already have your project environment activated, you can activate it using ``source .tvm/bin/activate``, and then you will be able to use the pip command.
 
 
 Uninstall Tutor Plugins
@@ -115,7 +115,7 @@ Pip
     pip uninstall <plugin>
 
 
-.. note:: If you don't already have your project environment activated, you can activate it using `source .tvm/bin/activate`, and then you will be able to use the pip command.
+.. note:: If you don't already have your project environment activated, you can activate it using ``source .tvm/bin/activate``, and then you will be able to use the pip command.
 
 
 Related

diff --git a/docs/source/tvm_topic_guides/version_manager.rst b/docs/source/tvm_topic_guides/version_manager.rst
@@ -84,7 +84,7 @@ List Environments and Projects
     tvm list
 
 
-.. note:: You can use the flag -l or --limit and an integer to limit the output. Ex: `tvm list --limit 10`
+.. note:: You can use the flag -l or --limit and an integer to restrict the output. E.g. ``tvm list --limit 10``
 
 
 Install Tutor Plugins
@@ -108,7 +108,7 @@ Pip
     pip install <plugin>
 
 
-.. note:: If you don't already have your project environment activated, you can activate it using `source .tvm/bin/activate`, and then you will be able to use the pip command.
+.. note:: If you don't already have your project environment activated, you can activate it using ``source .tvm/bin/activate``, and then you will be able to use the pip command.
 
 
 Uninstall Tutor Plugins
@@ -133,7 +133,7 @@ Pip
     pip uninstall <plugin>
 
 
-.. note:: If you don't already have your project environment activated, you can activate it using `source .tvm/bin/activate`, and then you will be able to use the pip command.
+.. note:: If you don't already have your project environment activated, you can activate it using ``source .tvm/bin/activate``, and then you will be able to use the pip command.
 
 
 Related

diff --git a/docs/source/tvm_tutorials/creating_two_dev_env.rst b/docs/source/tvm_tutorials/creating_two_dev_env.rst
@@ -1,7 +1,7 @@
 Creating two development environments
 ######################################
 
-At the end of this Tutorial, you will have two different TVM Projects to have two development environments.
+At the end of this tutorial, you will have two different TVM projects in two separate development environments.
 
 Step by Step
 -------------
@@ -43,7 +43,7 @@ Step by Step
 
     .. code-block:: bash
 
-        tutor dev quickstart
+        tutor dev launch
 
 #.  Stop your project.
 
@@ -59,7 +59,7 @@ Step by Step
 
 #.  Repeat steps 3 to 8 using the project-name and tutor-version you want.
 
-.. note::  You can have as many projects as you want, but you can't have two projects with the same name and tutor version.
+.. note:: You can have as many projects as you want, but you can not have two projects with the same name and tutor version.
 
 Next Steps
 -----------