This fixes a problem that we accidentally introduced in a recent PR: the
`shell=True` setting requires that the arguments were passed as a single
string instead of a list. Passing as a string, in turn, is somewhat
problematic because the file names need to be escaped, and there is no
utility function to make this escaping cross-platform.
So, instead we'll use the standard `shell=False`, and invoke
`dartdoc_json.bat` on Windows instead of simply `dartdoc_json`. Hope
this would work.
<!--
The title of your PR on the line above should start with a [Conventional
Commit] prefix
(`fix:`, `feat:`, `docs:`, `test:`, `chore:`, `refactor:`, `perf:`,
`build:`, `ci:`,
`style:`, `revert:`). This title will later become an entry in the
[CHANGELOG], so please
make sure that it summarizes the PR adequately.
-->
# Description
<!--
Provide a description of what this PR is doing.
If you're modifying existing behavior, describe the existing behavior,
how this PR is changing it,
and what motivated the change. If this is a breaking change, specify
explicitly which APIs were
changed.
-->
@eukleshnin identified issues with building the documents locally on a
Windows workstation. Namely, the following was occurring:
```
reading sources... [ 2%] flame/layout/align_component
Exception occurred:
FileNotFoundError: [WinError 2]
```
This was determined to be a combination of several things.
1. In `dart_domain.py`, the `subprocess.run` calling dartdoc_json did
not have the shell parameter set to true. This solves the error about
the file not being found. This then generates errors that subsequent
references to the `temp_file` did not exist.
2. This was due to the default setting with Python `tempfile` where when
it determines the temp file has been closed, it deletes it; however, it
was still needed, so by setting the `delete=False` parameter, the file
would still remain.
3. Unfortunately, because it still remains, it needs to be deleted once
it is no longer needed. Trying to use `finally:` with the `try` block
failed to produce the results desired, so the temp file name was
registered with the class so it can be deleted in the original calling
function if it exists. This proved successful.
4. Although not critical, the same temp file uses a suffix of `json` so
it was creating files `xxxxjson`. By adding the "." in the suffix, it
creates valid file names now. This doesn't actually fix anything, it
just seemed wrong, so I fixed it to be valid files if ever needed down
the road.
Now that the docs built, there were several warnings that could be
resolved:
1. `Overlays.md` was not referenced in the TOC tree.
2. Since overlays were removed in
https://github.com/flame-engine/flame/pull/2384, the Platformer tutorial
had a link to the old path and it needed to be updated.
Finally and open for discussion, during this process of debugging, I
upgraded all packages to the most current to see what impacts there
were. The following is the old and new potential `requirements.txt`:
```
----Old
linkify-it-py==2.0.0
myst-parser==0.18.1
Pygments==2.12.0
Sphinx==5.0.2
sphinxcontrib-mermaid==0.8.1
sphinx-autobuild==2021.3.14
jinja2==3.1.2
----- New
linkify-it-py==2.0.0
myst-parser==1.0.0
Pygments==2.14.0
Sphinx==6.1.3
sphinxcontrib-mermaid==0.8.1
sphinx-autobuild==2021.3.14
Jinja2==3.1.2
```
The only byproduct of this upgrade was a deprecated package warning for
`attrs_image` in `conf.py` which was updated to `attrs_inline`. I made
that change initially for this PR, but backed it out as I didn't know if
there was a desire to update the `requirements.txt` and felt some
discussion may be warranted.
Regardless, with everything upgraded or left as is, the other fixes
resolve the issues on Windows.
## Checklist
<!--
Before you create this PR confirm that it meets all requirements listed
below by checking the
relevant checkboxes with `[x]`. If some checkbox is not applicable, mark
it as `[-]`.
-->
- [X] I have followed the [Contributor Guide] when preparing my PR.
- [ ] I have updated/added tests for ALL new/updated/fixed
functionality.
- [X] I have updated/added relevant documentation in `docs` and added
dartdoc comments with `///`.
- [ ] I have updated/added relevant examples in `examples` or `docs`.
## Breaking Change?
<!--
Would your PR require Flame users to update their apps following your
change?
If yes, then the title of the PR should include "!" (for example,
`feat!:`, `fix!:`). See
[Conventional Commit] for details. Also, for a breaking PR uncomment and
fill in the "Migration
instructions" section below.
### Migration instructions
If the PR is breaking, uncomment this header and add instructions for
how to migrate from the
currently released version to the new proposed way.
-->
- [ ] Yes, this PR is a breaking change.
- [X] No, this PR is not a breaking change.
## Related Issues
<!--
Indicate which issues this PR resolves, if any. For example:
Closes#1234
!-->
<!-- Links -->
[Contributor Guide]:
https://github.com/flame-engine/flame/blob/main/CONTRIBUTING.md
[Conventional Commit]: https://conventionalcommits.org
[CHANGELOG]:
https://github.com/flame-engine/flame/blob/main/CHANGELOG.md
---------
Co-authored-by: Lukas Klingsbo <me@lukas.fyi>
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`
