The docs of the latest version say "1.7.0" will now go into the
directory "latest" instead of "1.7.0". This commit will now point the
docs to the new location.
This PR is a simultaneous work with flame-engine/flame-docs-site#15
when overflow-y, the scroll will be enabled on hover that makes us
scroll through the contents and click what's below
# Description
Initially, the contents section (the right side nav) doesn't scroll when
overflow. This PR adds the functionality to scroll when it overflows
vertically.
Working video:
https://user-images.githubusercontent.com/40348358/227519288-805ae943-0c23-4220-8224-fec168bae599.mov
### a small case to consider
This commit had some complications like having to compromise with having
shrink width. It doesn't much shrink, but does slightly does.
Before this PR:
<img width="1237" alt="Screenshot 2023-03-24 at 17 43 18"
src="https://user-images.githubusercontent.com/40348358/227519653-84c503a2-8ab4-460a-96b7-17c31d60ce62.png">
After this PR:
<img width="1238" alt="Screenshot 2023-03-24 at 17 42 54"
src="https://user-images.githubusercontent.com/40348358/227519701-bce512d7-e6df-459b-a3a1-5762a05f2934.png">
But, I am thinking this can be considered as the readability isn't
effected much as this sidebar only is visible when there is enough space
(more width).
## 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.
- [-] 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?
- [-] Yes, this PR is a breaking change.
- [x] No, this PR is not a breaking change.
## Related Issues
Closes#2423
As mentioned in discord, the current build of the docs loses jQuery
functionality. This is due to sphinx being upgraded to version 6 in
which they removed jQuery and created a stand-alone package for it.
Additionally, in the process of doing that, I noticed the previously
mentioned fix (in the comments) for the `melos doc-setup` about removing
the single quotes to keep it clean didn't make into the final code. I
have updated that as it was previously confirmed to work on all
platforms in: https://github.com/flame-engine/flame/pull/2401
I noticed that the copyright that was in the `conf.py` was locked at
2021 and so I made it go to 2023 as well. This can be removed if not
desired, but thought maybe this had just been overlooked.
Finally, there was an error regarding a duplicate instantiation of a
constant. This had to do with the fact the basic theme provided with
sphinx, the next version after which the docs were based, had a bug fix
implemented:
https://www.sphinx-doc.org/en/master/changes.html#release-5-1-0-released-jul-24-2022.
In their fix, it also broke the way the flames theme works. On a side
note, the docs are using a very outdated version of the basic theme and
should likely be overhauled, but that is outside the scope of this pr.
None the less, after I finally figured out how the basic theme is
inherited and where that lived on my machine, I was able to resolve the
discrepancies and eliminate the conflicting names between the two
themes.
In short, all errors have been resolved and I have confirmed that
mobile, web, search, highlighting, menus, etc. all work - at least on my
machine.
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.
Embedded flutter-app joints examples didn't work, because flutter-app script expects the example page to be located in the lib folder of a module. Introduced a new subfolder param, to specify where to find the example page.
Verified joints examples apps and code button on the doc page work; Also verified the same for the effects page.
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.
<!--
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>
The link went directly to the Flame channel instead of being an invite link to the server, so it didn't work for people that weren't already on the server.
This fixes the regression with that the graphs aren't rendering.
Unfortunately they will forever be broken in the v1.6.0 release of the
docs now.
Fix comes from here:
2eaff4220a
This creates a new component HardwareKeyboardDetector, which is a more advanced version of the KeyboardEvents mixin:
HardwareKeyboardDetector is a component instead of a mixin, which means it can be added/removed by the user at any point;
multiple such detectors can be attached to a game - for example, in a 2-player game one component may be paying attention to arrow keys, while another to WASD keys;
the new component uses Flutter's HardwareKeyboard interface, bypassing the need for a Focus widget;
the component keeps the ordered list of keys that are currently being pressed, which is helpful for games where this order is important;
there is the ability to temporarily pause the reception of key events using keyEventsPaused property.
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`
The new command allows pre-declaring the characters that will be seen in the yarn scripts, and provides a place to store any additional information associated with each character.
The DialogueLine.character property now returns a Character object, instead of a String.
Currently if you navigate to any inner page on the documentation site, say https://docs.flame-engine.org/main/tutorials/platformer/step_5.html, then the menus on the left that are currently collapsed can be expanded, but those that are already expanded cannot be collapsed (try clicking on the arrow next to "Tutorials" or "Ember Quest"). This PR fixes that.
This PR adds missing documentation for all built-in functions available in Jenny.
In addition:
The bool() function now behaves the same way as the conversion of arguments for an invocation of a user-defined function;
Consequently, static sets trueValues/falseValues moved from CommandStorage class into the YarnProject;
Added some tests for several other functions.
Class UserDefinedCommand now exposes argumentString and arguments properties, allowing them to be queried in a DialogueView;
Make sure the arguments of a user-defined command are computed only once per invocation;
Added documentation for user-defined commands;
addDialogueCommand renamed into addOrphanedCommand.
This commit makes a few css style changes in order that the language tags for code blocks in documentation site remains same even when horizontally scrolled.
Along with the above, this commit adds right padding to the code as to not come under the language tag when reaching the end.
This PR introduces class ValueRoute<T> that can be used together with the RouterComponent in order to create routes that return a value. The most common example of such routes are dialog boxes.
add an event listener to the docs site to listen everytime on load, then
expand the first expandable section ("flame") if the current page is
home page.
add an event listener to the docs site to listen everytime on load, then
expand the first expandable section ("flame") if the current page is
home page.
