wip: Implement prototype

Author: pawamoy

README.md

@@ -6,7 +6,7 @@
 [![gitpod](https://img.shields.io/badge/gitpod-workspace-blue.svg?style=flat)](https://gitpod.io/#https://github.com/mkdocstrings/typescript)
 [![gitter](https://badges.gitter.im/join%20chat.svg)](https://gitter.im/mkdocstrings/typescript)
 
-A Typescript handler for mkdocstrings.
+A Typescript handler for mkdocstrings. :warning: **Work in progress** :warning:
 
 ## Installation
 

docs/insiders/goals.yml

@@ -1 +1,6 @@
-goals: {}
+goals:
+  2000:
+    name: FusionDrive Ejection Configuration
+    features:
+    - name: "[Project] A TypeScript handler for mkdocstrings"
+      ref: /

mkdocs.yml

@@ -112,6 +112,12 @@ plugins:
 - coverage
 - mkdocstrings:
     handlers:
+      typescript:
+        options:
+          heading_level: 1
+          show_root_heading: true
+          show_symbol_type_toc: true
+          show_symbol_type_heading: true
       python:
         import:
         - https://docs.python.org/3/objects.inv

pyproject.toml

@@ -28,7 +28,8 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "mkdocstrings>=0.18",
+    "mkdocstrings>=0.24",
+    "griffe-typedoc>=0.0",
 ]
 
 [project.urls]

scripts/gen_credits.py

@@ -25,10 +25,34 @@
 lock_data = toml.load(project_dir / "pdm.lock")
 lock_pkgs = {pkg["name"].lower(): pkg for pkg in lock_data["package"]}
 project_name = project["name"]
-regex = re.compile(r"(?P<dist>[\w.-]+)(?P<spec>.*)$")
+with project_dir.joinpath("devdeps.txt").open() as devdeps_file:
+    devdeps = [line.strip() for line in devdeps_file if not line.startswith("-e")]
 
+PackageMetadata = Dict[str, Union[str, Iterable[str]]]
+Metadata = Dict[str, PackageMetadata]
 
-def _get_license(pkg_name: str) -> str:
+
+def _merge_fields(metadata: dict) -> PackageMetadata:
+    fields = defaultdict(list)
+    for header, value in metadata.items():
+        fields[header.lower()].append(value.strip())
+    return {
+        field: value if len(value) > 1 or field in ("classifier", "requires-dist") else value[0]
+        for field, value in fields.items()
+    }
+
+
+def _norm_name(name: str) -> str:
+    return name.replace("_", "-").replace(".", "-").lower()
+
+
+def _requirements(deps: list[str]) -> dict[str, Requirement]:
+    return {_norm_name((req := Requirement(dep)).name): req for dep in deps}
+
+
+def _extra_marker(req: Requirement) -> str | None:
+    if not req.marker:
+        return None
     try:
         data = metadata(pkg_name)
     except PackageNotFoundError:
@@ -48,7 +72,32 @@ def _get_license(pkg_name: str) -> str:
     return license_name or "?"
 
 
-def _get_deps(base_deps: Mapping[str, Mapping[str, str]]) -> dict[str, dict[str, str]]:
+def _get_metadata() -> Metadata:
+    metadata = {}
+    for pkg in distributions():
+        name = _norm_name(pkg.name)  # type: ignore[attr-defined,unused-ignore]
+        metadata[name] = _merge_fields(pkg.metadata)  # type: ignore[arg-type]
+        metadata[name]["spec"] = set()
+        metadata[name]["extras"] = set()
+        metadata[name].setdefault("summary", "")
+        _set_license(metadata[name])
+    return metadata
+
+
+def _set_license(metadata: PackageMetadata) -> None:
+    license_field = metadata.get("license-expression", metadata.get("license", ""))
+    license_name = license_field if isinstance(license_field, str) else " + ".join(license_field)
+    check_classifiers = license_name in ("UNKNOWN", "Dual License", "") or license_name.count("\n")
+    if check_classifiers:
+        license_names = []
+        for classifier in metadata["classifier"]:
+            if classifier.startswith("License ::"):
+                license_names.append(classifier.rsplit("::", 1)[1].strip())
+        license_name = " + ".join(license_names)
+    metadata["license"] = license_name or "?"
+
+
+def _get_deps(base_deps: dict[str, Requirement], metadata: Metadata) -> Metadata:
     deps = {}
     for dep in base_deps:
         parsed = regex.match(dep).groupdict()  # type: ignore[union-attr]

scripts/gen_ref_nav.py

@@ -4,14 +4,16 @@
 
 from typing import TYPE_CHECKING, Any, ClassVar, Mapping, MutableMapping
 
-from mkdocs.exceptions import PluginError
+from markdown import Markdown
 from mkdocstrings.handlers.base import BaseHandler, CollectionError, CollectorItem
 from mkdocstrings.loggers import get_logger
 
-if TYPE_CHECKING:
-    from markdown import Markdown
 
+from griffe_typedoc.loader import load as load_typedoc
+from griffe_typedoc.logger import patch_loggers
+from griffe_typedoc.dataclasses import ReflectionKind
 
+patch_loggers(get_logger)
 logger = get_logger(__name__)
 
 
@@ -31,9 +33,53 @@ class TypescriptHandler(BaseHandler):
     """The configuration used to collect item during autorefs fallback."""
 
     default_config: ClassVar[dict] = {
+        "base_file_path": ".",
+        "docstring_style": "google",
+        "docstring_options": {},
+        "show_symbol_type_heading": False,
+        "show_symbol_type_toc": False,
         "show_root_heading": False,
         "show_root_toc_entry": True,
+        "show_root_full_path": True,
+        "show_root_members_full_path": False,
+        "show_object_full_path": False,
+        "show_category_heading": False,
+        "show_if_no_docstring": False,
+        "show_signature": True,
+        "show_signature_annotations": False,
+        "signature_crossrefs": False,
+        "separate_signature": False,
+        "line_length": 60,
+        "merge_init_into_class": False,
+        "show_docstring_attributes": True,
+        "show_docstring_functions": True,
+        "show_docstring_classes": True,
+        "show_docstring_modules": True,
+        "show_docstring_description": True,
+        "show_docstring_examples": True,
+        "show_docstring_other_parameters": True,
+        "show_docstring_parameters": True,
+        "show_docstring_raises": True,
+        "show_docstring_receives": True,
+        "show_docstring_returns": True,
+        "show_docstring_warns": True,
+        "show_docstring_yields": True,
+        "show_source": True,
+        "show_bases": True,
+        "show_submodules": False,
+        "group_by_category": True,
         "heading_level": 2,
+        "members_order": "alphabetical",
+        "docstring_section_style": "table",
+        "members": None,
+        "inherited_members": False,
+        "filters": ["!^_[^_]"],
+        "annotations_path": "brief",
+        "preload_modules": None,
+        "allow_inspection": True,
+        "summary": False,
+        "unwrap_annotated": False,
+        "parameter_headings": False,
     }
     """The default configuration options.
 
@@ -44,6 +90,11 @@ class TypescriptHandler(BaseHandler):
     **`heading_level`** | `int` | The initial heading level to use. | `2`
     """
 
+    def __init__(self, *args, **kwargs) -> None:
+        config_file_path = kwargs.pop("config_file_path", None)
+        super().__init__(*args, **kwargs)
+        self._collected = {}
+
     def collect(self, identifier: str, config: MutableMapping[str, Any]) -> CollectorItem:  # noqa: ARG002
         """Collect data given an identifier and selection configuration.
 
@@ -60,8 +111,22 @@ def collect(self, identifier: str, config: MutableMapping[str, Any]) -> Collecto
         Returns:
             Anything you want, as long as you can feed it to the `render` method.
         """
-        raise CollectionError("Implement me!")
-
+        if config.get("fallback", False):
+            raise CollectionError("Not loading modules during fallback")
+        if identifier not in self._collected:
+            data = load_typedoc(["typedoc"])
+            if data.kind is ReflectionKind.PROJECT:
+                self._collected.update({module.name: module for module in data.children})
+            else:
+                self._collected[data.name] = data
+            logger.debug(f"Collected {', '.join(self._collected.keys())}")
+        if identifier in self._collected:
+            for child in self._collected[identifier].children:
+                if child.kind is ReflectionKind.MODULE and child.name == "index":
+                    return child
+            return self._collected[identifier]
+        raise CollectionError(f"Could not collect {identifier}")
+        
     def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:  # noqa: ARG002
         """Render a template using provided data and configuration options.
 
@@ -73,13 +138,12 @@ def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:  # noqa
         Returns:
             The rendered template as HTML.
         """
-        # final_config = {**self.default_config, **config}
-        # heading_level = final_config["heading_level"]
-        # template = self.env.get_template(f"{data...}.html")
-        # return template.render(
-        #     **{"config": final_config, data...: data, "heading_level": heading_level, "root": True},
-        # )
-        raise PluginError("Implement me!")
+        final_config = {**self.default_config, **config}
+        heading_level = final_config["heading_level"]
+        template = self.env.get_template(f"module.html")
+        return template.render(
+            **{"config": final_config, "module": data, "heading_level": heading_level, "root": True},
+        )
 
     def update_env(self, md: Markdown, config: dict) -> None:
         """Update the Jinja environment with any custom settings/filters/options for this handler.
@@ -116,7 +180,5 @@ def get_handler(
         handler="typescript",
         theme=theme,
         custom_templates=custom_templates,
-        # To pass the following argument,
-        # you'll need to override the handler's __init__ method.
-        # config_file_path=config_file_path,
+        config_file_path=config_file_path,
     )

src/mkdocstrings_handlers/typescript/handler.py

@@ -0,0 +1,29 @@
+{% if obj.kind.value == "module" and obj.exports %}
+  {% with children = obj.exports %}
+    {% if children %}
+      {{ log.debug("Rendering children of " + obj.path) }}
+      <div class="doc doc-children">
+        {% for obj in children %}
+          {% include "dispatch.html" with context %}
+        {% endfor %}
+      </div>
+    {% endif %}
+  {% endwith %}
+{% elif obj.groups %}
+  {{ log.debug("Rendering groups of " + obj.path) }}
+  <div class="doc doc-children">
+    {% for group in obj.resolved_groups %}
+      <b>{{ group.title }}</b>
+      {% for obj in group.children %}
+        {% include "dispatch.html" with context %}
+      {% endfor %}
+    {% endfor %}
+  </div>
+{% elif obj.children %}
+  {{ log.debug("Rendering children of " + obj.path) }}
+  <div class="doc doc-children">
+    {% for obj in obj.children %}
+      {% include "dispatch.html" with context %}
+    {% endfor %}
+  </div>
+{% endif %}