Refactored structure of documentation; added :doc:FAQ section <faq/index> (#2732)

* move tutorials -> tutorials_guide

* change title in tutorials_guides

* rename: a_deeper_look -> output_and_config

* splitting Tutorials

* reorder index (sidebar), move some top level sections elsewhere

* rename some tutorials

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* replace recommonmark with rest for rendering md files

* fixed broken references

* fixed **all** warnings and errors during docbuild

* faq: help, more structure for landing page

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix deprecation tests

* prepare some sort of skeleton for installation faq

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* ensure that pip from poetry venv is used in pipeline

* added myst-parser as dev dependency

* remove fixed sphinx version from requirement.txt, don't re-install dependencies

* move and improve versions and troubleshooting content to FAQ

* resolve broken references

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* help blacken-docs

* new: navigating the docs

* make different versions question more prominent

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fixed order of tutorials

* added explicit references to building blocks and quickstart tutorial

* docs -> doc

* change a page-reference to a paragraph-reference

* pypi manimlib, split answer regarding chocolatey failing

* added a note on #beginner-resources

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: behackl

.github/workflows/ci.yml

@@ -57,7 +57,7 @@ jobs:
 
       - name: Run doctests in rst files
         run: |
-          cd docs && pip install -r requirements.txt && poetry run make doctest O=-tskip-manim
+          cd docs && poetry run make doctest O=-tskip-manim
 
 
   test:

docs/i18n/readyForTranslation

@@ -9,6 +9,6 @@ examples.po
 reference.po
 tutorials.po
 tutorials/building_blocks.po
-tutorials/a_deeper_look.po
+tutorials/output_and_config.po
 tutorials/quickstart.po
 tutorials/configuration.po

docs/requirements.txt

@@ -1,5 +1,5 @@
-sphinx==4.1.2
 furo
-recommonmark>=0.5.0
+myst-parser
+sphinx
 sphinx-copybutton
 sphinxext-opengraph

docs/source/changelog/0.14.0-changelog.rst

@@ -111,7 +111,7 @@ Documentation-related changes
 * :pr:`2415`: Removed instructions on using and installing Docker in README
 
 
-* :pr:`2414`: Made improvements to the :doc:`configuration` tutorial
+* :pr:`2414`: Made improvements to the :doc:`/guides/configuration` tutorial
 
 
 * :pr:`2423`: Changed recommendation to ``mactex-no-gui`` from ``mactex`` for macOS install

docs/source/conf.py

@@ -35,7 +35,6 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "recommonmark",
     "sphinx_copybutton",
     "sphinx.ext.napoleon",
     "sphinx.ext.autosummary",
@@ -47,6 +46,7 @@
     "sphinx.ext.graphviz",
     "sphinx.ext.inheritance_diagram",
     "sphinxcontrib.programoutput",
+    "myst_parser",
 ]
 
 # Automatically generate stub pages when using the .. autosummary directive

docs/source/contributing/development.rst

@@ -154,11 +154,6 @@ Develop your contribution
       Use the :mod:`manim directive for Sphinx <manim.utils.docbuild.manim_directive>` to add examples
       to the documentation!
 
-      .. autosummary::
-         :toctree: ../reference
-
-         manim.utils.docbuild.manim_directive
-
 As far as development on your local machine goes, these are the main steps you
 should follow.
 
@@ -282,7 +277,7 @@ Further useful guidelines
 
 
 You can find examples for the ``docs`` in several places:
-the :doc:`Example Gallery <../examples>`, :doc:`Tutorials <../tutorials>`,
+the :doc:`Example Gallery <../examples>`, :doc:`Tutorials <../tutorials/index>`,
 and :doc:`Reference Classes <../reference>`.
 
 In case you are contributing, please have a look at this flowchart:

docs/source/faq/general.md

@@ -0,0 +1,197 @@
+# FAQ: General Usage
+
+## Why does Manim say that "there are no scenes inside that module"?
+
+There are two main reasons why this error appears: if you have edited
+the file containing your `Scene` class and forgot to save it, or if you
+have accidentally passed the name of a wrong file to `manim`, this is
+a likely outcome. Check that you have spelled everything correctly.
+
+Otherwise you are likely mixing up Manim versions. See {ref}`this FAQ answer <different-versions>`
+for an explanation regarding why there are different versions. Under the assumption
+that you are trying to use the `manim` executable from the terminal to run
+a scene that has been written for the community version (i.e., there is
+`from manim import *`, or more specifically `from manim import Scene`)
+
+---
+
+## No matter what code I put in my file, Manim only renders a black frame! Why?
+
+If you are using the usual pattern to write a `Scene`, i.e.,
+```python
+class MyAwesomeScene(Scene):
+    def construct(self):
+        ...
+        # your animation code
+```
+then double check whether you have spelled `construct` correctly.
+If the method containing your code is not called `construct` (or
+if you are not calling a different, custom method from `construct`),
+Manim will not call your method and simply output a black frame.
+
+---
+
+## I have watched a video where a creator ran command X, but it does not work for me. Why?
+
+The video you have been watching is likely outdated. If you want to follow
+along, you either need to use the same version used in the video, or
+modify the code (in many cases it is just a method having been renamed etc.)
+accordingly. Check the video description, in some cases creators point out
+whether changes need to be applied to the code shown in the video.
+
+---
+
+## When using `Tex` or `MathTex`, some letters are missing. How can I fix this?
+
+It is possible that you have to (re)build some fonts used by LaTeX. For
+some distributions, you can do this manually by running
+```bash
+fmtutil -sys --all
+```
+We recommend consulting the documentation of your LaTeX distribution
+for more information.
+
+---
+
+## I want to translate some code from `manimgl` to `manim`, what do I do with `CONFIG` dictionaries?
+
+The community maintained version has dropped the use of `CONFIG` dictionaries very
+early, with {doc}`version v0.2.0 </changelog/0.2.0-changelog>` released in
+January 2021.
+
+Before that, Manim's classes basically processed `CONFIG` dictionaries
+by mimicking inheritance (to properly process `CONFIG` dictionaries set
+by parent classes) and then assigning all of the key-value-pairs in the
+dictionary as attributes of the corresponding object.
+
+In situations where there is not much inheritance going on,
+or for any custom setting, you should set these attributes yourself.
+For example, for an old-style `Scene` with custom attributes like
+
+```python
+class OldStyle(Scene):
+    CONFIG = {"a": 1, "b": 2}
+```
+
+should be written as
+
+```python
+class NewStyle(Scene):
+    a = 1
+    b = 2
+```
+
+In situations where values should be properly inherited, the arguments
+should be added to the initialization function of the class. An old-style
+mobject `Thing` could look like
+
+```python
+class Thing(VMobject):
+    CONFIG = {
+        "stroke_color": RED,
+        "fill_opacity": 0.7,
+        "my_awesome_argument": 42,
+    }
+```
+
+where `stroke_color` and `fill_opacity` are arguments that concern the
+parent class of `Thing`, and `my_awesome_argument` is a custom argument
+that only concerns `Thing`. A version without `CONFIG` could look like this:
+
+```python
+class Thing(VMobject):
+    def __init__(
+        self, stroke_color=RED, fill_opacity=0.7, my_awesome_argument=42, **kwargs
+    ):
+        self.my_awesome_argument = my_awesome_argument
+        super().__init__(stroke_color=stroke_color, fill_opacity=fill_opacity, **kwargs)
+```
+
+---
+
+## My installation does not support converting PDF to SVG, help?
+
+This is an issue with `dvisvgm`, the tool shipped with LaTeX that
+transforms LaTeX output to a `.svg` file that
+Manim can parse.
+
+First, make sure your ``dvisvgm`` version is at least 2.4 by
+checking the output of
+
+```bash
+dvisvgm --version
+```
+
+If you do not know how to update `dvisvgm`, please refer to your
+LaTeX distributions documentation (or the documentation of your
+operating system, if `dvisvgm` was installed as a system package).
+
+Second, check whether your ``dvisvgm`` supports PostScript specials. This is
+needed to convert from PDF to SVG. Run:
+
+```bash
+dvisvgm -l
+```
+
+If the output to this command does **not** contain `ps  dvips PostScript specials`,
+this is a bad sign. In this case, run
+
+```bash
+dvisvgm -h
+```
+
+If the output does **not** contain `--libgs=filename`, this means your
+`dvisvgm` does not currently support PostScript. You must get another binary.
+
+If, however, `--libgs=filename` appears in the help, that means that your
+`dvisvgm` needs the Ghostscript library to support PostScript. Search for
+`libgs.so` (on Linux, probably in `/usr/local/lib` or `/usr/lib`) or
+`gsdll32.dll` (on 32-bit Windows, probably in `C:\windows\system32`) or
+`gsdll64.dll` (on 64-bit Windows, also probably in `C:\windows\system32`)
+or `libgsl.dylib` (on MacOS, probably in `/usr/local/lib` or
+`/opt/local/lib`). Please look carefully, as the file might be located
+elsewhere, e.g. in the directory where Ghostscript is installed.
+
+When you have found the library, try (on MacOS or Linux)
+
+```bash
+export LIBGS=<path to your library including the file name>
+dvisvgm -l
+```
+
+or (on Windows)
+
+```bat
+set LIBGS=<path to your library including the file name>
+dvisvgm -l
+```
+
+You should now see `ps    dvips PostScript specials` in the output. Refer to
+your operating system's documentation to find out how you can set or export the
+environment variable ``LIBGS`` automatically whenever you open a shell.
+
+As a last check, you can run
+
+```bash
+dvisvgm -V1
+```
+
+(while still having `LIBGS` set to the correct path, of course.) If `dvisvgm`
+can find your Ghostscript installation, it will be shown in the output together
+with the version number.
+
+If you do not have the necessary library on your system, please refer to your
+operating system's documentation to find out where you can get it and how you
+have to install it.
+
+If you are unable to solve your problem, check out the
+[dvisvgm FAQ](https://dvisvgm.de/FAQ/).
+
+---
+
+## Where can I find more resources for learning Manim?
+
+In our [Discord server](https://manim.community/discord), we have the community maintained
+`#beginner-resources` channel in which links to helpful learning resources are collected.
+You are welcome to join our Discord and take a look yourself! If you have found some
+guides or tutorials yourself that are not on our list yet, feel free to add them!

docs/source/faq/help.md

@@ -0,0 +1,105 @@
+# FAQ: Getting Help
+
+## How do I animate X? Why do I get error Y? Can someone help me?
+
+Before asking the community, please make sure that the issue you are having
+is not already discussed in our {doc}`FAQ section </faq/index>` sufficiently
+well so that you can resolve the problem yourself. You can also try to
+use your favorite search engine, if you are lucky you might find a blog post,
+a question on [StackOverflow](https://stackoverflow.com/questions/tagged/manim),
+or a post in the [r/manim subreddit](https://reddit.com/r/manim).
+
+If this is not the case, please take a moment to properly prepare your question:
+the better you manage to explain what exactly it is you are struggling with,
+the more efficient people will be able to help you. Regardless of the platform
+you choose in the next step, StackOverflow has a good guide on
+[asking good questions](https://stackoverflow.com/help/how-to-ask).
+
+As soon as you have a good idea of what exactly you want to ask, pick one of the
+following communication channels:
+
+- The community is most active [in our Discord server](https://manim.community/discord/).
+  Click the link to join, then pick one of the `#manim-help` channels in the sidebar,
+  and post your question there. If you are comfortable with using Discord, try to search
+  for your problem using the search function of our server; perhaps people have been
+  talking about it before!
+- We are also monitoring questions on
+  [StackOverflow](https://stackoverflow.com/questions/tagged/manim) that are tagged
+  with `manim`.
+- Many people are also active in our [r/manim subreddit](https://reddit.com/r/manim),
+  feel free to post there if you are an avid Redditor -- but be aware that Discord
+  or StackOverflow might be better choices.
+- And finally, you can also start a new [discussion on GitHub](https://github.com/ManimCommunity/manim/discussions)
+  if you dislike all other options.
+
+In all of these channels, please make sure to abide by Manim's
+{doc}`Code of Conduct </conduct>` -- in short, be *excellent* to one another:
+be friendly and patient, considerate, and respectful.
+
+---
+
+## What should I do if nobody answers my question?
+
+Try and see whether your question can be improved: did you include all relevant
+information (in case of errors: the full stack trace, the code that you were
+rendering, and the command you used to run Manim?). In case you used a very long
+example, is it possible to construct a more minimal version that has the same
+(faulty) behavior?
+
+If you posted in one of our help channels on Discord and your question got buried,
+you are allowed to ping the `@Manim Helper` role to bring it to the attention of
+the volunteers who are willing to take a look. Please refrain from pinging the role
+immediately when asking your question for the first time, this is considered impolite.
+
+You can also try to post your question to a different channel if you feel that you
+are not having any success with your initial choice -- but please do not spam your
+question in all of our communication channels (and in particular for Discord:
+please don't use multiple help channels at once).
+
+In the end, it is as for most open-source projects: our community members are
+volunteers. If you do not receive a quick answer to your question, it may be
+because nobody knows the answer, or because your question is not clear enough,
+or it could be that everyone who can help you with your problem is busy doing
+other things.
+
+---
+
+## The library does not behave as documented, or something broke in a new release. What should I do?
+
+Sounds like you have found a bug. One of the best ways of contributing to the
+development of Manim is by reporting it!
+
+Check our list of known issues and feature requests
+[in our GitHub repository](https://github.com/ManimCommunity/manim/issues). If the
+problem you have found is not listed there yet (use the search function; also check
+whether there is a corresponding closed issue, it is possible that your problem
+has already been resolved and will be fixed with the next release), please consider
+the following steps to submit a new issue.
+
+```{note}
+If you are unsure whether or not you should file a new issue for some odd behavior
+that you found, feel free to ask the community developers, preferably in one of
+our `#manim-dev` channels in [our Discord](https://manim.community/discord/).
+```
+
+1. Make sure you are running the latest released version of Manim, your problem
+   might otherwise already be fixed in a more recent version. Check the
+   {doc}`/changelog` for a full list of changes between Manim releases.
+
+2. Choose the correct category for your report when
+   [creating a new issue](https://github.com/ManimCommunity/manim/issues/new/choose).
+   We have dedicated issue templates for *bug reports*, *feature requests*,
+   *installation issues*, and *suggestions*. If your report falls into one of these
+   categories, read the issue template carefully! Instructions are given in the
+   `<!-- ... -->` sections of the text field.
+
+3. For bug reports: prepare a minimal example that can be used to illustrate the
+   issue. Examples with hundreds of lines are very inefficient and tedious to debug.
+   Your problem needs to be reproducible for others, so please make sure to prepare
+   a suitable example.
+
+4. This is mentioned in the bug report template as well, but it is very important:
+   if you report that some code raises an error, make sure to include the full
+   terminal output, from the command you used to run the library up to and including
+   the last line with the error message. Read carefully: if the message mentions
+   that there is another relevant log file, include this other file as well!

docs/source/faq/index.rst

@@ -0,0 +1,9 @@
+Frequently Asked Questions
+==========================
+
+.. toctree::
+   :caption: Table of Contents
+   :maxdepth: 2
+   :glob:
+
+   *