From 8045a3337f9250368d92fc5d88fd8a9ca5a57c8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9rome=20Eertmans?= Date: Thu, 18 Jan 2024 21:54:13 +0100 Subject: [PATCH] chore(docs): make it better --- README.md | 25 +++--- docs/source/contributing/workflow.md | 37 ++++++++- docs/source/index.md | 2 +- docs/source/installation.md | 88 +++++++++++++++------ docs/source/quickstart.md | 62 +-------------- docs/source/reference/sharing.md | 2 +- manim_slides/docs/manim_slides_directive.py | 4 +- manim_slides/ipython/ipython_magic.py | 4 +- 8 files changed, 123 insertions(+), 101 deletions(-) diff --git a/README.md b/README.md index a954b892..cadfd056 100644 --- a/README.md +++ b/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,14 +92,15 @@ 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 @@ -109,6 +108,13 @@ manim-slides BasicExample +

+ Manim Slides Logo +

+ +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 @@ -116,17 +122,12 @@ 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 diff --git a/docs/source/contributing/workflow.md b/docs/source/contributing/workflow.md index f4b10254..fe936c83 100644 --- a/docs/source/contributing/workflow.md +++ b/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 diff --git a/docs/source/index.md b/docs/source/index.md index 542ee5bd..d8a2f46d 100644 --- a/docs/source/index.md +++ b/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 diff --git a/docs/source/installation.md b/docs/source/installation.md index c5002507..d93f81df 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -1,19 +1,29 @@ # Installation - - 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. +::: - +## 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) @@ -21,40 +31,74 @@ If none of those packages are installed, please refer to their specific installa 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). ::: - - -### 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. - - diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md index 7539503a..68424e8e 100644 --- a/docs/source/quickstart.md +++ b/docs/source/quickstart.md @@ -1,65 +1,7 @@ # Quickstart -## Installation - - - -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 - - - -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. -::: - - - -### 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. - - +If not already, install Manim Slides, along with either Manim or ManimGL, +see [installation](./installation). ## Creating your first slides diff --git a/docs/source/reference/sharing.md b/docs/source/reference/sharing.md index c6e9258b..88c4e4a4 100644 --- a/docs/source/reference/sharing.md +++ b/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 diff --git a/manim_slides/docs/manim_slides_directive.py b/manim_slides/docs/manim_slides_directive.py index 25835180..62f1270d 100644 --- a/manim_slides/docs/manim_slides_directive.py +++ b/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 diff --git a/manim_slides/ipython/ipython_magic.py b/manim_slides/ipython/ipython_magic.py index 25f42b7c..bb28a197 100644 --- a/manim_slides/ipython/ipython_magic.py +++ b/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