docs: Create "dart" domain extension (#2278)

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}
:package: 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`

doc/_sphinx/conf.py

@@ -4,11 +4,15 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 import docutils
+import docutils.nodes
 import html
 import os
 import sys
 sys.path.insert(0, os.path.abspath('.'))
 
+root_dir = os.path.abspath(
+ os.path.join(os.path.dirname(__file__), '..', '..')
+)
 
 # -- Project information -----------------------------------------------------
 
@@ -20,12 +24,15 @@
 
 # -- General configuration ---------------------------------------------------
 
+primary_domain = 'dart'
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
  'myst_parser', # Markdown support
  'sphinxcontrib.mermaid',
+ 'extensions.dart_domain',
  'extensions.flutter_app',
  'extensions.package',
  'extensions.yarn_lexer',
@@ -61,6 +68,12 @@
  r'https://pub.dev/documentation/flame/--VERSION--/',
 ]
 
+# -- Options for dartdoc extension -------------------------------------------
+dartdoc_roots = {
+ 'flame': os.path.join(root_dir, 'packages/flame/lib'),
+ 'jenny': os.path.join(root_dir, 'packages/flame_jenny/jenny/lib'),
+}
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.

doc/_sphinx/extensions/dart_domain.css

@@ -0,0 +1,45 @@
+
+.dartdoc .signature.sig1 {
+ background: black;
+ background: linear-gradient(0deg, #000 0%, #000000bb 65%, #00000088 100%);
+ font-family: var(--font-mono);
+ margin: 8pt -30pt;
+ padding: 12pt 30pt;
+}
+
+.dartdoc .signature.sig2 {
+ border-radius: 6pt;
+ box-shadow: 1px 1px 3px rgb(0 0 0 / 50%);
+ font-family: var(--font-mono);
+ margin-bottom: 6pt;
+ padding: 6pt 6pt 6pt 30pt;
+ text-indent: -21pt;
+}
+
+.dartdoc .signature .keyword { opacity: 0.5; }
+.dartdoc .signature .name { color: white; }
+.dartdoc .sig1 .name { font-weight: bold; }
+.dartdoc .signature .argument { white-space: pre; }
+.dartdoc .signature .argument .name { color: #999; }
+.dartdoc .signature .punct { color: #ffd68d; }
+.dartdoc .signature .types { margin-left: 2pt; }
+.dartdoc .signature .modifier { margin-left: 40pt; }
+.dartdoc .doc2 { margin-left: 30pt; }
+
+.dartdoc .constructor { margin-bottom: 12pt; }
+.dartdoc .constructor .signature { background: rgb(59 116 30 / 25%); }
+.dartdoc .method .signature { background: rgb(69 102 167 / 25%); }
+.dartdoc .field .signature,
+.dartdoc .getter .signature,
+.dartdoc .setter .signature { background: rgb(63 92 86 / 25%); }
+
+.dartdoc span.param {
+ background: #111;
+ border: 1px solid rgb(170 204 221 / 50%);
+ border-radius: 3pt;
+ color: #a6c3de;
+ font-family: var(--font-mono);
+ font-size: 85%;
+ padding: 1pt 3pt;
+ white-space: nowrap;
+}