chore(docs): make it better

README.md

@@ -38,7 +38,7 @@ Manim Slides will *automatically* detect the one you are using!
 
 Manim Slides requires either Manim or ManimGL to be installed, along
 with their dependencies. Please checkout the
-[documentation](https://eertmans.be/manim-slides/)
+[documentation](https://eertmans.be/manim-slides/installation.html)
 for detailed install instructions.
 
 ## Usage
@@ -61,8 +61,6 @@ animations, and `self.next_slide(loop=True)` if you want the next slide to loop
 over animations until the user presses continue:
 
 ```python
-# example.py
-
 from manim import *  # or: from manimlib import *
 
 from manim_slides import Slide
@@ -94,39 +92,42 @@ manim-slides render --GL example.py BasicExample
 > [!NOTE]
 > Using `manim-slides render` makes sure the use the `manim`
 > (or `manimlib`) library that was installed in the Python same environment.
+> Put simply, this is a wrapper of `manim render [ARGS]...` (or `manimgl [ARGS]...`).
 
-To start the presentation using `Scene1`, `Scene2` and so on simply run:
+To start the presentation using `Scene1`, `Scene2` and so on, run:
 
 ```bash
 manim-slides [OPTIONS] Scene1 Scene2...
 ```
 
-Or in this example:
+In our example:
 
 ```bash
 manim-slides BasicExample
 ```
 
 <!-- end usage -->
 
+<p align="center">
+  <img alt="Manim Slides Logo" src="https://raw.githubusercontent.com/jeertmans/manim-slides/main/static/example.gif">
+</p>
+
+For detailed usage documentation, run `manim-slides --help`, or go to the
+[documentation](https://eertmans.be/manim-slides/reference/cli.html).
+
 ## Interactive Tutorial
 
 Click on the image to watch a slides presentation that explains to you how
 to use Manim Slides.
 
 [![Manim Slides Docs](https://raw.githubusercontent.com/jeertmans/manim-slides/main/static/docs.png)](https://eertmans.be/manim-slides/)
 
-## Other Examples
+## More Examples
 
-Other examples are available in the
+More examples are available in the
 [`example.py`](https://github.com/jeertmans/manim-slides/blob/main/example.py)
 file, if you downloaded the git repository.
 
-Below is a small recording of me playing with the slides back and forth.
-
-![](https://raw.githubusercontent.com/jeertmans/manim-slides/main/static/example.gif)
-
-
 ## Comparison with Similar Tools
 
 There exists a variety of tools that allows to create slides presentations

docs/source/contributing/workflow.md

@@ -82,12 +82,43 @@ manim-slides wizard
 ## Testing your code
 
 Most of the tests are done with GitHub actions, thus not on your computer.
-The only command you should run locally is `pdm run pre-commit run --all-files`:
-this runs a few linter and formatter to make sure the code quality and style stay
+The only command you should run locally is:
+
+```bash
+pdm run pre-commit run --all-files
+```
+
+This runs a few linter and formatter to make sure the code quality and style stay
 constant across time.
 If a warning or an error is displayed, please fix it before going to next step.
 
-For testing your code, simply run `pdm run pytest`.
+For testing your code, simply run:
+
+```bash
+pdm run pytest
+```
+
+## Building the documentation
+
+The documentation is generated using Sphinx, based on the content
+in `docs/source` and in the `manim_slides` Python package.
+
+To generate the documentation, run the following:
+
+```bash
+cd docs
+pdm run make html
+```
+
+Then, the output index file is located at `docs/build/html/index.html` and
+can be opened with any modern browser.
+
+:::{warning}
+Building the documentation can take quite some time, especially
+the first time as it needs to render all the animations.
+
+Further builds should run faster.
+:::
 
 ## Proposing changes
 

docs/source/index.md

@@ -26,7 +26,6 @@ Manim Slides makes creating slides with Manim super easy!
 In a [very few steps](./quickstart),
 you can create slides and present them either using the GUI, or your browser.
 
-
 Slide through the demo below to get a quick glimpse on what you can do with
 Manim Slides.
 
@@ -40,6 +39,7 @@ Manim Slides.
 :hidden:
 
 quickstart
+installation
 reference/index
 features_table
 manim_or_manimgl

docs/source/installation.md

@@ -1,60 +1,104 @@
 # Installation
 
-<!-- start install -->
-
 While installing Manim Slides and its dependencies on your global Python is fine,
 we recommend using a virtual environment
 (e.g., [venv](https://docs.python.org/3/tutorial/venv.html)) for a local installation.
 
-### Dependencies
+Therefore, the following documentation will install Manim Slides using
+[pipx](https://pipx.pypa.io/). This tool is a drop-in replacement
+for installing Python packages that ship with one or more executable.
+
+The benefit of using pipx is that it will automatically create a new virtual
+environment for every package you install.
+
+:::{note}
+Everytime you read `pipx install`, you can use `pip install` instead,
+if you are working in a virtual environment or else.
+:::
 
-<!-- start deps -->
+## Dependencies
 
-Manim Slides requires either Manim or ManimGL to be installed.
+Manim Slides requires either Manim or ManimGL to be installed, along
+with their dependencies.
 Having both packages installed is fine too.
 
-If none of those packages are installed, please refer to their specific installation guidelines:
+If none of those packages are installed,
+please refer to their specific installation guidelines:
 - [Manim](https://docs.manim.community/en/stable/installation.html)
 - [ManimGL](https://3b1b.github.io/manim/getting_started/installation.html)
 
 :::{warning}
 If you install Manim from its git repository, as suggested by ManimGL,
 make sure to first check out a supported version (e.g., `git checkout tags/v1.6.1`
 for ManimGL), otherwise it might install an unsupported version of Manim!
-See [#314](https://github.com/jeertmans/manim-slides/issues/314) for an example.
+See [#314](https://github.com/jeertmans/manim-slides/issues/314).
 :::
 
-<!-- end deps -->
-
-### Pip Install
-
-:::{note}
-For an easy and safe installation, use [`pipx`](https://pipx.pypa.io/)
-instead of `pip`.
-:::
+## Pip Install
 
 The recommended way to install the latest release is to use pip:
 
 ```bash
-pipx install manim-slides
+pipx install -U manim-slides
 ```
 
+:::{tip}
+While not necessary, the `-U` indicates that we would
+like to upgrade to the latest version available,
+if Manim Slides is already installed.
+:::
+
 Optionally, you can also install Manim or ManimGL using extras[^1]:
 
 ```bash
-pip install "manim-slides[manim]"   # For Manim
+pipx install -U "manim-slides[manim]"   # For Manim
 # or
-pip install "manim-slides[manimgl]" # For ManimGL
+pipx install -U "manim-slides[manimgl]" # For ManimGL
+```
+
+You can check that Manim Slides was correctly installed with:
+
+```bash
+manim-slides --version
 ```
 
+:::{warning}
+If you are installing with pipx, this is mandatory to at least include
+either `manim` or `manimgl`.
+:::
+
 [^1]: You still need to have Manim or ManimGL platform-specific dependencies
   installed on your computer.
 
-### Install From Repository
+## Optional Dependencies
+
+Along with the optional dependencies for Manim and ManimGL,
+Manim Slides offers additional *extras*, that can be activated
+using optional dependencies:
+
+- `magic`, to include a Jupyter magic to render
+  animations inside notebooks. This automatically installs `manim`,
+  and does not work with ManimGL;
+- `manim` and `manimgl`, for installing the corresponding
+  dependencies;
+- `sphinx-directive`, to generate presentation inside your Sphinx
+  documentation. This automatically installs `manim`,
+  and does not work with ManimGL;
+
+Installing those extras can be done with the following syntax:
+
+```bash
+pipx install -U "manim-slides[extra1,extra2]"
+```
+
+:::{note}
+The quotes `"` are added because not all shell support unquoted
+brackets (e.g., zsh) or commas (e.g., Windows).
+:::
+
+## Install From Repository
 
 An alternative way to install Manim Slides is to clone the git repository,
 and install from there: read the
-[contributing guide](https://eertmans.be/manim-slides/contributing/workflow.html)
+[contributing guide](./contributing/workflow)
 to know how to process.
-
-<!-- end install -->

docs/source/quickstart.md

@@ -1,65 +1,7 @@
 # Quickstart
 
-## Installation
-
-<!-- start install -->
-
-While installing Manim Slides and its dependencies on your global Python is fine,
-we recommend using a virtual environment
-(e.g., [venv](https://docs.python.org/3/tutorial/venv.html)) for a local installation.
-
-### Dependencies
-
-<!-- start deps -->
-
-Manim Slides requires either Manim or ManimGL to be installed.
-Having both packages installed is fine too.
-
-If none of those packages are installed, please refer to their specific installation guidelines:
-- [Manim](https://docs.manim.community/en/stable/installation.html)
-- [ManimGL](https://3b1b.github.io/manim/getting_started/installation.html)
-
-:::{warning}
-If you install Manim from its git repository, as suggested by ManimGL,
-make sure to first check out a supported version (e.g., `git checkout tags/v1.6.1`
-for ManimGL), otherwise it might install an unsupported version of Manim!
-See [#314](https://github.com/jeertmans/manim-slides/issues/314) for an example.
-:::
-
-<!-- end deps -->
-
-### Pip Install
-
-:::{note}
-For an easy and safe installation, use [`pipx`](https://pipx.pypa.io/)
-instead of `pip`.
-:::
-
-The recommended way to install the latest release is to use pip:
-
-```bash
-pipx install manim-slides
-```
-
-Optionally, you can also install Manim or ManimGL using extras[^1]:
-
-```bash
-pip install "manim-slides[manim]"   # For Manim
-# or
-pip install "manim-slides[manimgl]" # For ManimGL
-```
-
-[^1]: You still need to have Manim or ManimGL platform-specific dependencies
-  installed on your computer.
-
-### Install From Repository
-
-An alternative way to install Manim Slides is to clone the git repository,
-and install from there: read the
-[contributing guide](https://eertmans.be/manim-slides/contributing/workflow.html)
-to know how to process.
-
-<!-- end install -->
+If not already, install Manim Slides, along with either Manim or ManimGL,
+see [installation](./installation).
 
 ## Creating your first slides
 

docs/source/reference/sharing.md

@@ -97,7 +97,7 @@ By default, the assets directory will be named after the main HTML file, using `
 
 Example:
 
-```raw
+```
 .
 ├── basic_example_assets
 │   ├── 1413466013_2261824125_223132457.mp4

manim_slides/docs/manim_slides_directive.py

@@ -21,7 +21,9 @@
 with Sphinx.
 You can install them manually, or with the extra keyword:
 
-    pip install manim-slides[sphinx-directive]
+.. code-block:: bash
+
+    pip install "manim-slides[sphinx-directive]"
 
 Note that you will still need to install Manim's platform-specific dependencies,
 see

manim_slides/ipython/ipython_magic.py

@@ -16,7 +16,9 @@
 This magic requires two additional dependencies: ``manim`` and ``IPython``.
 You can install them manually, or with the extra keyword:
 
-    pip install manim-slides[magic]
+.. code-block:: bash
+
+    pip install "manim-slides[magic]"
 
 Note that you will still need to install Manim's platform-specific dependencies,
 see