docs: add dev guide of tinymist-query (#1064)

crates/tinymist-query/README.md

@@ -14,4 +14,4 @@ Also see [Developer Guide: Tinymist Query](https://myriad-dreamin.github.io/tiny
 
 ## Contributing
 
-See [CONTRIBUTING.md](https://github.com/Myriad-Dreamin/tinymist/blob/main/CONTRIBUTING.md).
+See [CONTRIBUTING.md](https://github.com/Myriad-Dreamin/tinymist/blob/main/CONTRIBUTING.md) and [Guide to develop `tinymist-query`](https://github.com/Myriad-Dreamin/tinymist/blob/main/docs/dev-guide/tinymist-query.md).

crates/tinymist-query/src/fixtures/completion/README.md

@@ -0,0 +1,8 @@
+
+# Fixtures
+
+This is the fixtures directory that testing the [`textDocument/completion`](/crates/tinymist-query/src/completion.rs) function. 
+
+## Contributing
+
+Please check [CONTRIBUTING.md](/CONTRIBUTING.md) and [Guide to develop `tinymist-query`](/docs/dev-guide/tinymist-query.md#testing-analyzers).

crates/tinymist-query/src/goto_definition.rs

@@ -7,7 +7,7 @@ use crate::prelude::*;
 ///
 /// # Compatibility
 ///
-/// The [`GotoDefinitionResponse::Link`](lsp_types::GotoDefinitionResponse::Link) return value
+/// The [`GotoDefinitionResponse::Link`] return value
 /// was introduced in specification version 3.14.0 and requires client-side
 /// support in order to be used. It can be returned if the client set the
 /// following field to `true` in the `initialize` method:

crates/tinymist-query/src/jump.rs

@@ -1,6 +1,4 @@
-//! The [`CompileServerActor`] implementation borrowed from typst.ts.
-//!
-//! Please check `tinymist::actor::typ_client` for architecture details.
+//! Jumping from and to source and the rendered document.
 
 use std::num::NonZeroUsize;
 

docs/dev-guide.md

@@ -88,6 +88,8 @@ cargo insta test -p tinymist-query --accept
 > [!Tip]
 > Check [Cargo Insta](https://insta.rs/docs/cli/) to learn and install the `insta` command.
 
+To add more tests, please refer to the guide to [test analyzers.](./dev-guide/tinymist-query.md#testing-analyzers)
+
 ## Running Syntax Grammar Tests
 
 This is required if you are going to change the textmate grammar in `syntaxes/textmate`.

docs/dev-guide/tinymist-query.md

@@ -0,0 +1,122 @@
+
+# `tinymist-query` analyzer library
+
+## Documentation
+
+The documentation can be generated locally by running:
+
+```bash
+yarn docs:rs --open # You can also copy-run the command if you don't have a yarn.
+```
+
+## Name Convention
+
+The names of analyzers are all have suffix `Worker`. To get a full list of analyzers, please search "struct: tinymist_query worker" in Cargo Docs.
+
+```rust
+tinymist_query::analysis::bib::BibWorker
+tinymist_query::syntax::expr::ExprWorker
+tinymist_query::syntax::index::IndexWorker
+tinymist_query::analysis::link_expr::LinkStrWorker
+tinymist_query::analysis::OnEnterWorker
+tinymist_query::analysis::color_expr::ColorExprWorker
+tinymist_query::analysis::InlayHintWorker
+...
+```
+
+## Testing analyzers
+
+To run analyzer tests for tinymist:
+
+```bash
+cargo insta test -p tinymist-query --accept
+```
+
+> [!Tip]  
+> Check [Cargo Insta](https://insta.rs/docs/cli/) to learn and install the `insta` command.
+
+To add a test, for example for the [`textDocument/completion`](/crates/tinymist-query/src/completion.rs) function, please follow the steps:
+
+1. Check the first argument of `snapshot_testing` function calls in the source file. We know that it uses fixtures from [`fixtures/completion/`](/crates/tinymist-query/src/fixtures/completion/).
+2. Add a typst file in the [`fixtures/completion/`](/crates/tinymist-query/src/fixtures/completion/) directory.
+3. Rerun the `cargo insta` command to update snapshot.
+
+At the step 2, we have special syntax to write the typst file.
+
+1. Cursor range to request completion: `/* range -1..0 */` or `/* range after 1..2 */` that relative to the comment node.
+
+    Example:
+
+    ```typ
+    $: /* range -1..0 */$
+    ```
+
+    It test completion when the cursor is after a colon in the equation context.
+2. Completion result filter: `/// contains: comma separated list`
+
+    Example:
+    
+    ```typ
+    /// contains: body, fill
+    #set text(/* range 0..1 */ )
+    ```
+
+    Description: The snapshot result **must** contains `fill` and **must not** contains `body`, so we add both of them to the `contains` list.
+
+3. Fixture of some multiple-files project:  `/// path: file name`
+
+    Example:
+
+    ```typ
+    /// path: base.typ
+    #let table-prefix() = 1;
+
+    -----
+    /// contains: base,table,table-prefix
+    #import "base.typ": table/* range -1..1 */
+    ```
+
+    Description: the files are separated by `-----`, and the first file is named `base.typ`. The snapshot result **must not** contain `base`, `table`, and **must** contain `table-prefix`, so we add them to the `contains` list.
+
+4. Whether to compile the file: `/// compile: true`
+
+    Example:
+
+    ```typ
+    /// compile: true
+
+    #let test1(body) = figure(body)
+    #test1([Test1]) <fig:test1>
+    /* position after */ @fig:test1
+    ```
+
+    Description: The file will be compiled before the test, to get the content reference by `typst::trace` for completion.
+
+4. Compile which the file: `/// compile: base.typ`
+
+    Example:
+
+    ```typ
+    /// compile: true
+
+   /// path: base.typ
+    #set heading(numbering: "1.1")
+
+    = H <t>
+
+    == H2 <test>
+
+    aba aba
+
+    -----
+    /// contains: test
+    /// compile: base.typ
+
+    #<t /* range -2..-1 */
+    ```
+
+    Description: Another file named `base.typ` will be compiled before the test, since a half-editing file causes the completion to fail.
+
+## Analyzer playground
+
+A special fixture folder [`playground`](/crates/tinymist-query/src/fixtures/playground/) is provided for testing analyzers. You can change argument of the `snapshot_testing` to `"playground"` or `""` to use the playground fixtures.

package.json

@@ -17,7 +17,7 @@
     "maintainers": "typst query MAINTAINERS.typ \"<maintainer-meta>\" --pretty --one --field value --input=action=help",
     "docs": "shiroa serve --font-path assets/fonts -w . docs/tinymist",
     "docs:typ": "node scripts/link-docs.mjs",
-    "docs:rs": "cargo doc --workspace --no-deps",
+    "docs:rs": "cargo doc --workspace --document-private-items --no-deps",
     "test:grammar": "cd syntaxes/textmate && yarn run test",
     "build:typlite": "cargo build --bin typlite",
     "typlite": "target/debug/typlite",