From a32773c50f0d46b8a9288025727954f048cbf8c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A9rome=20Eertmans?= <jeertmans@icloud.com>
Date: Fri, 3 Mar 2023 21:56:00 +0100
Subject: [PATCH] chore(docs): adding GUI and HTML documentation pages (#145)

* chore(docs): adding GUI and HTML documentation pages

As titled, this adds two pages to the docs

* fix(typo): languagetool suggestion
---
 docs/source/_static/wizard_dark.png  |  1 +
 docs/source/_static/wizard_light.png |  1 +
 docs/source/conf.py                  |  5 ++
 docs/source/reference/gui.md         | 71 ++++++++++++++++++++++++++++
 docs/source/reference/html.md        | 40 ++++++++++++++++
 docs/source/reference/index.md       | 12 ++++-
 6 files changed, 128 insertions(+), 2 deletions(-)
 create mode 120000 docs/source/_static/wizard_dark.png
 create mode 120000 docs/source/_static/wizard_light.png
 create mode 100644 docs/source/reference/gui.md
 create mode 100644 docs/source/reference/html.md

diff --git a/docs/source/_static/wizard_dark.png b/docs/source/_static/wizard_dark.png
new file mode 120000
index 0000000..ed73bb3
--- /dev/null
+++ b/docs/source/_static/wizard_dark.png
@@ -0,0 +1 @@
+../../../static/wizard_dark.png
\ No newline at end of file
diff --git a/docs/source/_static/wizard_light.png b/docs/source/_static/wizard_light.png
new file mode 120000
index 0000000..e2ad159
--- /dev/null
+++ b/docs/source/_static/wizard_light.png
@@ -0,0 +1 @@
+../../../static/wizard_light.png
\ No newline at end of file
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 897ecc0..cc8f7d4 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -24,6 +24,11 @@ extensions = [
     "sphinx_copybutton",
 ]
 
+myst_enable_extensions = [
+    "colon_fence",
+    "html_admonition",
+]
+
 templates_path = ["_templates"]
 exclude_patterns = []
 
diff --git a/docs/source/reference/gui.md b/docs/source/reference/gui.md
new file mode 100644
index 0000000..1f1574d
--- /dev/null
+++ b/docs/source/reference/gui.md
@@ -0,0 +1,71 @@
+# Graphic User Interface
+
+Manim Slides' graphical user interface (GUI) is the *de facto* way to present slides.
+
+If you do not specify one of the commands listed in the [CLI reference](./cli),
+Manim Slides will use **present** by default, which launches a GUI window,
+playing your scene(s) like so:
+
+```bash
+manim-slides [present] [SCENES]...
+```
+
+Some optional parameters can be specified and can be listed with:
+
+```bash
+manim-slides present --help
+```
+
+:::{note}
+All the `SCENES` must be in the same folder (`--folder DIRECTORY`), which
+defaults to `./slides`. If you rendered your animations without changing
+directory, you should not worry about that :-)
+:::
+
+## Configuration File
+
+It is possible to configure Manim Slides via a configuration file, even though
+this feature is currently limited. You may initiliaze the default configuration
+file with:
+
+```bash
+manim-slides init
+```
+
+:::{warning}
+Note that, by default, Manim Slides will use default key bindings that are
+platform-dependent. If you decide to overwrite those with a config file, you may
+encounter some problems from platform to platform.
+:::
+
+## Configuring Key Bindings
+
+If you wish to use other key bindings than the defaults, you can run the
+configuration wizard with:
+
+```bash
+manim-slides wizard
+```
+
+A similar window to the image below will pop up and prompt to change keys.
+
+```{eval-rst}
+.. image:: ../_static/wizard_light.png
+    :width: 300px
+    :align: center
+    :class: only-light
+    :alt: Manim Slide Wizard
+```
+
+```{eval-rst}
+.. image:: ../_static/wizard_dark.png
+    :width: 300px
+    :align: center
+    :class: only-dark
+    :alt: Manim Slide Wizard
+```
+
+:::{note}
+Even though it is not currently supported through the GUI, you can select
+multiple key binding for the same action by modifying the config file.
+:::
diff --git a/docs/source/reference/html.md b/docs/source/reference/html.md
new file mode 100644
index 0000000..ba58f84
--- /dev/null
+++ b/docs/source/reference/html.md
@@ -0,0 +1,40 @@
+# HTML Presentations
+
+Manim Slides allows you to convert presentations into one HTML file, with
+[RevealJS](https://revealjs.com/). This file can then be opened with any modern
+web browser, allowing for a nice portability of your presentations.
+
+As for every command with Manim Slides, converting slides' fragments into one
+HTML file (and its assets) can be done in one command:
+
+```bash
+manim-slides convert [SCENES]... DEST
+```
+
+where `DEST` is the `.html` destination file.
+
+## Configuring the Template
+
+Many configuration options are available through the `-c<option>=<value>` syntax.
+Most, if not all, RevealJS options should be available by default. If that is
+not the case, please
+[fill an issue](https://github.com/jeertmans/manim-slides/issues/new/choose)
+on GitHub.
+
+You can print the list of available options with:
+
+```bash
+manim-slides convert --show-config
+```
+
+## Using a Custom Template
+
+The default template used for HTML conversion can be found on
+[GitHub](https://github.com/jeertmans/manim-slides/blob/main/manim_slides/data/revealjs_template.html)
+or printed with the `--show-template` option.
+If you wish to use another template, you can do so with the
+`--use-template FILE` option.
+
+## More about HTML Slides
+
+You can read more about HTML slides in the [sharing](./sharing) section.
diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md
index c91e3bb..d2cf2a1 100644
--- a/docs/source/reference/index.md
+++ b/docs/source/reference/index.md
@@ -8,13 +8,21 @@ Automatically generated reference for Manim Slides.
 api
 cli
 examples
+gui
+html
 sharing
 ```
 
-[Application Programming Interface](./api): list of classes and methods that may be useful to the end-user.
+[Application Programming Interface](./api): list of classes and methods that may
+be useful to the end-user.
 
-[Command Line Interface](./cli): list of all commands available using Manim Slides' executable.
+[Command Line Interface](./cli): list of all commands available using Manim
+Slides' executable.
 
 [Examples](./examples): curated list of examples and their output.
 
+[Graphical User Interface](./gui): details about the main Manim Slide' feature.
+
+[HTML Presenetation](./html): an alternative way of presenting your animations.
+
 [Sharing](./sharing): how to share your presentation with others.