docs: Update documentation

Author: pawamoy

README.md

@@ -66,7 +66,21 @@ Again, update entrypoints to match your file and package layout. See [TypeDoc's
 
 You are now able to use the TypeScript handler to inject API docs in your Markdown pages by referencing package names:
 
-```python
+```md
 ::: @owner/packageName
     handler: typescript
 ```
+
+You can set the Typescript handler as default handler:
+
+```yaml
+plugins:
+- mkdocstrings:
+    default_handler: typescript
+```
+
+By setting it as default handler you can omit it when injecting documentation:
+
+```md
+::: @owner/packageName
+```

docs/css/material.css

@@ -2,3 +2,25 @@
 .md-main__inner {
   margin-bottom: 1.5rem;
 }
+
+/* Custom admonition: preview */
+:root {
+  --md-admonition-icon--preview: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15.5 12a3.5 3.5 0 1 1-7 0 3.5 3.5 0 0 1 7 0Z"/><path d="M12 3.5c3.432 0 6.124 1.534 8.054 3.241 1.926 1.703 3.132 3.61 3.616 4.46a1.6 1.6 0 0 1 0 1.598c-.484.85-1.69 2.757-3.616 4.461-1.929 1.706-4.622 3.24-8.054 3.24-3.432 0-6.124-1.534-8.054-3.24C2.02 15.558.814 13.65.33 12.8a1.6 1.6 0 0 1 0-1.598c.484-.85 1.69-2.757 3.616-4.462C5.875 5.034 8.568 3.5 12 3.5ZM1.633 11.945a.115.115 0 0 0-.017.055c.001.02.006.039.017.056.441.774 1.551 2.527 3.307 4.08C6.691 17.685 9.045 19 12 19c2.955 0 5.31-1.315 7.06-2.864 1.756-1.553 2.866-3.306 3.307-4.08a.111.111 0 0 0 .017-.056.111.111 0 0 0-.017-.056c-.441-.773-1.551-2.527-3.307-4.08C17.309 6.315 14.955 5 12 5 9.045 5 6.69 6.314 4.94 7.865c-1.756 1.552-2.866 3.306-3.307 4.08Z"/></svg>');
+}
+
+.md-typeset .admonition.preview,
+.md-typeset details.preview {
+  border-color: rgb(220, 139, 240);
+}
+
+.md-typeset .preview>.admonition-title,
+.md-typeset .preview>summary {
+  background-color: rgba(142, 43, 155, 0.1);
+}
+
+.md-typeset .preview>.admonition-title::before,
+.md-typeset .preview>summary::before {
+  background-color: rgb(220, 139, 240);
+  -webkit-mask-image: var(--md-admonition-icon--preview);
+  mask-image: var(--md-admonition-icon--preview);
+}

docs/usage/configuration/general.md

@@ -12,6 +12,7 @@ Local `extra` options will be merged into the global `extra` option:
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
 - mkdocstrings:
+    default_handler: typescript
     handlers:
       typescript:
         options:
@@ -20,10 +21,10 @@ plugins:
 ```
 
 ```md title="in docs/some_page.md (local configuration)"
-::: your_package.your_module.your_func
+::: @owner/packageName
     options:
       extra:
         foo: bar
 ```
 
-...will inject both `hello` and `foo` into the Jinja context when rendering `your_package.your_module.your_func`.
+...will inject both `hello` and `foo` into the Jinja context when rendering `@owner/packageName`.

docs/usage/configuration/headings.md

@@ -10,7 +10,7 @@ A custom string to use as the heading of the root object (i.e. the object specif
 WARNING: **Not advised to be used as a global configuration option.** This option is not advised to be used as a global configuration option, as it will override the default heading for all objects. It is recommended to use it only in specific cases where you want to override the heading for a specific object.
 
 ```md title="in docs/some_page.md (local configuration)"
-::: path.to.module
+::: @owner/package
     options:
       heading: "My fancy module"
 ```
@@ -32,14 +32,15 @@ If you set it to 3, then headings will start with `<h3>`.
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
 - mkdocstrings:
+    default_handler: typescript
     handlers:
       typescript:
         options:
           heading_level: 2
 ```
 
 ```md title="or in docs/some_page.md (local configuration)"
-::: path.to.module
+::: @owner/package
     options:
       heading_level: 3
 ```
@@ -102,14 +103,15 @@ To customize symbols, see [Customizing symbol types](../customization.md/#symbol
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
 - mkdocstrings:
+    default_handler: typescript
     handlers:
       typescript:
         options:
           show_symbol_type_heading: true
 ```
 
 ```md title="or in docs/some_page.md (local configuration)"
-::: package.module
+::: @owner/package
     options:
       show_symbol_type_heading: false
 ```
@@ -190,14 +192,15 @@ To customize symbols, see [Customizing symbol types](../customization.md/#symbol
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
 - mkdocstrings:
+    default_handler: typescript
     handlers:
       typescript:
         options:
           show_symbol_type_toc: true
 ```
 
 ```md title="or in docs/some_page.md (local configuration)"
-::: package.module
+::: @owner/package
     options:
       show_symbol_type_toc: false
 ```
@@ -262,8 +265,8 @@ WARNING: **Not advised to be used as a global configuration option.** This optio
 NOTE: **Use with/without `heading`.** If you use this option without specifying a custom `heading`, the default heading will be used in the page, but the label in the Table of Contents will be the one you specified. By providing both an option for `heading` and `toc_label`, we leave the customization entirely up to you.
 
 ```md title="in docs/some_page.md (local configuration)"
-::: path.to.module
+::: @owner/package
     options:
-      heading: "My fancy module"
-      toc_label: "My fancy module"
+      heading: "My fancy package"
+      toc_label: "My fancy package"
 ```

docs/usage/configuration/index.md

@@ -10,7 +10,7 @@ For example, globally:
 plugins:
 - mkdocstrings:
     handlers:
-      python:
+      typescript:
         options:
           do_something: true
 ```

docs/usage/index.md

@@ -0,0 +1,72 @@
+# Usage
+
+Add these [TypeDoc](https://typedoc.org/) configuration files to your repository:
+
+```tree hl_lines="4 5"
+./
+    src/
+        package1/
+    typedoc.base.json
+    typedoc.json
+```
+
+```json title="typedoc.base.json"
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "includeVersion": true
+}
+```
+
+```json title="typedoc.json"
+{
+  "extends": ["./typedoc.base.json"],
+  "entryPointStrategy": "packages",
+  "entryPoints": ["./src/*"]
+}
+```
+
+Update the entrypoints to match your file layout so that TypeDoc can find your packages. See [TypeDoc's configuration documentation](https://typedoc.org/options/configuration/).
+
+Then in each of your package, add this TypeDoc configuration file:
+
+```tree hl_lines="4"
+./
+    src/
+        package1/
+            typedoc.json
+    typedoc.base.json
+    typedoc.json
+```
+
+```json title="typedoc.json"
+{
+  "extends": ["../../typedoc.base.json"],
+  "entryPointStrategy": "expand",
+  "entryPoints": ["src/index.d.ts"]
+}
+```
+
+Again, update entrypoints to match your file and package layout. See [TypeDoc's configuration documentation](https://typedoc.org/options/configuration/).
+
+**Your packages must be built for TypeDoc to work.**
+
+You are now able to use the TypeScript handler to inject API docs in your Markdown pages by referencing package names:
+
+```md
+::: @owner/packageName
+    handler: typescript
+```
+
+You can set the Typescript handler as default handler:
+
+```yaml
+plugins:
+- mkdocstrings:
+    default_handler: typescript
+```
+
+By setting it as default handler you can omit it when injecting documentation:
+
+```md
+::: @owner/packageName
+```

mkdocs.yml

@@ -93,6 +93,12 @@ markdown_extensions:
 - admonition
 - callouts
 - footnotes
+- pymdownx.blocks.admonition
+- pymdownx.blocks.tab:
+    alternate_style: true
+    slugify: !!python/object/apply:pymdownx.slugs.slugify
+      kwds:
+        case: lower
 - pymdownx.emoji:
     emoji_index: !!python/name:material.extensions.emoji.twemoji
     emoji_generator: !!python/name:material.extensions.emoji.to_svg