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.
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`
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.
* Simpler css injection
* Better menu for selecting documentation version
* Auto-detect current docs version
* Use let/const instead of var, and single quotes
* Added versions file
* Updated script to use template strings
* Update script to load the list of versions dynamically
* Use main branch as a source for versions.txt file
