As mentioned in #2395, there are several lingering issues that can be solved by bumping the Python package requirements up. All packages need / can run on Python 3.8+, so the docs do not need to be updated regarding that.
This PR specifically fixes the following warnings:
flame\doc\bridge_packages\bridge_packages.md:4: WARNING: 'myst' reference target not found: ..\bridge_packages\flame_audio\flame_audio.md
....There were a lot of those....
`attrs_image` is deprecated. Use `attrs_inline` instead.
Additionally, this PR adds a new command melos doc-kill which executes the kill-server.py script. This script relies on psutil which has been added to the requirements.txt, but allows a cross platform ability to isolate and kill process threads that are locking the port 8000. This commonly happens when you exit melos doc-serve and the internal web server doesn't die as well. This may not be an issue for Unix platforms, but for Windows users its extremely annoying.
The only alternative for Windows users is to manually do:
netstat -ano | findstr :8000
// Then run:
taskkill /PID XXXXX /F
As I mentioned in the other PR, I split this out so it can be debated mainly for the bump in requirements; however, I feel the benefits are very worth it. I marked this as breaking just because it changes the base package requirements and adds a package which may not qualify as breaking, depending on how you look at it.
Edit: Forgot that this PR also fixes a typo in the melos doc-serve description and corrects the misspelling of everytime to every time.
In Sphinx, there is a concept of a "domain", which enables documenting library object such as classes and functions, and then referencing them from any other place in the documentation. This PR adds such a domain for the Dart language.
With the new approach, a class/function can be documented using the following directive:
```{dartdoc}
📦 flame
:symbol: GameWidget
:file: src/game/game_widget/game_widget.dart
```
The documentation will then be automatically extracted from the referenced file using the dartdoc_json tool (published as a separate package), and then rendered inside the page. The screenshot below shows an example of how DialogueRunner class from Jenny would be rendered:
<image>
Once a symbol has been documented using the dartdoc directive, it can be referenced from other places in the documentation as
{ref}`DialogueRunner`
This commit replaces the melos doc-build-live with melos doc-serve.
This also changes documentation for this while removing the mention of make commands in the documentation.
Fix several errors reported during documentation build.
Generally speaking,
```foo
would be interpreted as a code block with the language foo; while
```{foo}
would be interpreted as a Sphinx directive .. foo.
The Style Guide moved into the Documentation site for better visibility. Removed lots of discussion around topics that are already enforced by the formatter/linter. Added new advice regarding a variety of topics.
The Test Writing Guide discusses how to write tests for Flame, and what kinds of tests are available.
Additional mode "infobox" allows Flutter widgets to be inserted into the generated documentation site as wikipedia-style infoboxes floating on the right. This is useful for presenting content to the user up-front without sacrificing the flow of the exposition. For example, currently the Tap Events demo is "hidden" in the middle of a long page.
We believe that presenting the content in this way would make the user more excited to read about it.
