docs: Documenting how to write documentation (#1721)

Since our documentation is fairly complex, we need to have a document which describes how various parts of it work. This PR adds such documentation.

doc/README.md

@@ -82,7 +82,7 @@ Flame doesn't bundle any helpers to load assets from an external source (externa
 sources).
 
 But most of Flame's API can be loaded from concrete asset instances, for examples, `Sprite`s can be
-created from `dart:ui`s `Image` instaces, so the user can write custom code to load images from
+created from `dart:ui`s `Image` instances, so the user can write custom code to load images from
 anywhere they need, and then load it into Flame's classes.
 
 Here are some suggestions for http client packages:

doc/development/development.md

@@ -0,0 +1,5 @@
+# Development
+
+```{toctree}
+Documentation <documentation.md>
+```

doc/development/documentation.md

@@ -0,0 +1,168 @@
+# Documentation Site
+
+Flame's documentation is written in **Markdown**. It is then rendered into HTML with the help of
+the [Sphinx] engine and its [MyST] plugin. The rendered files are then manually (but with the help
+of a script) published to [flame-docs-site], where the site is served via [GitHub Pages].
+
+[Sphinx]: https://www.sphinx-doc.org/en/master/
+[MyST]: https://myst-parser.readthedocs.io/en/latest/
+[flame-docs-site]: https://github.com/flame-engine/flame-docs-site
+[GitHub Pages]: https://pages.github.com/
+
+
+## Markdown
+
+The main documentation site is written in Markdown. We assume that you're already familiar with the
+basics of the Markdown syntax (if not, there are plenty of guides on the Internet). Instead, this
+section will focus on the Markdown extensions that are enabled in our build system.
+
+
+### Table of contents
+
+The table of contents for the site must be created manually. This is done using special `{toctree}`
+blocks, one per each subdirectory:
+`````
+```{toctree}
+:hidden:
+
+First Topic <topic1.md>
+Second Topic <topic2.md>
+```
+`````
+When adding new documents into the documentation site, make sure that they are mentioned in one of
+the toctrees -- otherwise you will see a warning during the build that the document is orphaned.
+
+
+### Admonitions
+
+Admonitions are emphasized blocks of text with a distinct appearance. They are created using the
+triple-backticks syntax:
+`````
+```{note}
+Please note this very important caveat.
+```
+```{warning}
+Don't look down, or you will encounter an error.
+```
+```{error}
+I told you so.
+```
+```{seealso}
+Also check out this cool thingy.
+```
+`````
+```{note}
+Please note this very important caveat.
+```
+```{warning}
+Don't look down, or you will encounter an error.
+```
+```{error}
+I told you so.
+```
+```{seealso}
+Also check out this cool thingy.
+```
+
+
+### Deprecations
+
+The special `{deprecated}` block can be used to mark some part of documentation or syntax as being
+deprecated. This block requires specifying the version when the deprecation has occurred
+`````
+```{deprecated} v1.3.0
+
+Please use this **other** thing instead.
+```
+`````
+Which would be rendered like this:
+```{deprecated} v1.3.0
+
+Please use this **other** thing instead.
+```
+
+
+### Live examples
+
+Our documentation site includes a custom-built **flutter-app** directive which allows creating
+Flutter widgets and embedding them alongside with the overall documentation content.
+
+In Markdown, the code for inserting an embed looks like this:
+``````
+```{flutter-app}
+:sources: ../flame/examples
+:page: tap_events
+:show: widget code popup
+```
+``````
+Here's what the different options mean:
+- **sources**: specifies the name of the root directory where the Flutter code that you wish to run
+ is located. This directory must be a Flutter repository, and there must be a `pubspec.yaml` file
+ there. The path is considered relative to the `doc/_sphinx` directory.
+
+- **page**: a sub-path within the root directory given in `sources`. This option has two effects:
+ first, it is appended to the path of the html page of the widget, like so: `main.dart.html?$page`.
+ Secondly, the button to show the source code of the embed will display the code from the file or
+ directory with the name given by `page`.
+
+ The purpose of this option is to be able to bundle multiple examples into a single executable.
+ When using this option, the `main.dart` file of the app should route the execution to the proper
+ widget according to the `page` being passed.
+
+- **show**: contains a subset of modes: `widget`, `code`, and `popup`. The `widget` mode creates an
+ iframe with the embedded example, directly within the page. The `code` mode will show a button
+ that allows the user to see the code that produced this example. The `popup` mode also shows a
+ button, which displays the example in an overlay window. This is more suitable for demoing larger
+ apps. Using both "widget" and "popup" modes at the same time is not recommended.
+
+```{flutter-app}
+:sources: ../flame/examples
+:page: tap_events
+:show: widget code popup
+```
+
+
+## Building documentation locally
+
+Building the documentation site on your own computer is fairly simple. All you need is the
+following:
+
+1. A working **Flutter** installation, accessible from the command line;
+
+2. A **Python** environment, with python version 3.6 or higher;
+ - You can verify this by running `python --version` from the command line;
+ - Having a dedicated python virtual environment is recommended but not required;
+
+3. A set of python **modules** listed in the `doc/_sphinx/requirements.txt` file;
+ - The easiest way to install these is to run
+ ```console
+ $ pip install -r doc/_sphinx/requirements.txt
+ ```
+
+Once these prerequisites are met, you can build the documentation by switching to the `doc/_sphinx`
+directory and running `make html`:
+```console
+$ cd doc/_sphinx
+$ make html
+```
+
+The **make html** command here renders the documentation site into HTML. This command needs to be
+re-run every time you make changes to any of the documents. Luckily, it is smart enough to only
+rebuild the documents that have changed since the previous run, so usually a rebuild takes only
+a second or two.
+
+There are other make commands that you may find occasionally useful too: **make clean** removes all
+cached generated files (in case the system gets stuck in a bad state); and **make linkcheck** to
+check whether there are any broken links in the documentation.
+
+The generated html files will be in the `doc/_build/html` directory, you can view them directly
+by opening the file `doc/_build/html/index.html` in your browser. The only drawback is that the
+browser won't allow any dynamic content in a file opened from a local drive. The solution to this
+is to run your own local http server:
+```console
+$ python -m http.server 8000 --directory doc/_build/html
+```
+Then you can open the site at `http://localhost:8000/`.
+
+If you ever run the `make clean` command, the server will need to be restarted, because the clean
+command deletes the entire `html` directory.

doc/flame/flame.md

@@ -1,19 +1,16 @@
 # flame
 
-```{eval-rst}
-.. toctree::
- :hidden:
- 
- File structure <structure.md>
- GameWidget <game_widget.md>
- Game loop <game.md>
- Components <components.md>
- Platforms <platforms.md>
- Collision detection <collision_detection.md>
- Effects <effects.md>
- Camera & Viewport <camera_and_viewport.md>
- Camera component <camera_component.md>
- Inputs <inputs/inputs.md>
- Rendering <rendering/rendering.md>
- Other <other/other.md>
+```{toctree}
+File structure <structure.md>
+GameWidget <game_widget.md>
+Game loop <game.md>
+Components <components.md>
+Platforms <platforms.md>
+Collision detection <collision_detection.md>
+Effects <effects.md>
+Camera & Viewport <camera_and_viewport.md>
+Camera component <camera_component.md>
+Inputs <inputs/inputs.md>
+Rendering <rendering/rendering.md>
+Other <other/other.md>
 ```

doc/flame_audio/flame_audio.md

@@ -1,10 +1,7 @@
 # flame_audio
 
-```{eval-rst}
-.. toctree::
- :hidden:
-
- General audio <audio.md>
- Background music <bgm.md>
- AudioPool <audio_pool.md>
+```{toctree}
+General audio <audio.md>
+Background music <bgm.md>
+AudioPool <audio_pool.md>
 ```

doc/flame_forge2d/flame_forge2d.md

@@ -1,8 +1,5 @@
 # flame_forge2d
 
-```{eval-rst}
-.. toctree::
- :hidden:
-
- Overview <forge2d.md>
+```{toctree}
+Overview <forge2d.md>
 ```

doc/index.md

@@ -8,4 +8,5 @@ flame_audio <flame_audio/flame_audio.md>
 flame_forge2d <flame_forge2d/flame_forge2d.md>
 Tutorials <tutorials/tutorials.md>
 Other Modules <other_modules/other_modules.md>
+Development <development/development.md>
 ```

doc/other_modules/other_modules.md

@@ -1,10 +1,7 @@
 # Other Modules
 
-```{eval-rst}
-.. toctree::
- :hidden:
- 
- Oxygen <oxygen.md>
- Tiled <tiled.md>
- Splash screen <splash_screen.md>
+```{toctree}
+Oxygen <oxygen.md>
+Tiled <tiled.md>
+Splash screen <splash_screen.md>
 ```

packages/flame_flare/example/pubspec.yaml

@@ -8,16 +8,13 @@ environment:
  flutter: ^3.0.0
 
 dependencies:
- flame:
- path: ../../flame
- flame_flare:
- path: ../
+ flame: ^1.2.0
+ flame_flare: ^1.2.0
  flutter:
  sdk: flutter
 
 dev_dependencies:
- flame_lint:
- path: ../../flame_lint
+ flame_lint: ^0.1.0
 
 flutter:
  assets: