mkdocstrings-typescript 0.0.0__tar.gz → 0.0.1__tar.gz

mkdocstrings_typescript-0.0.1/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2023, Timothée Mazzucotelli
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

mkdocstrings_typescript-0.0.1/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.1
+Name: mkdocstrings-typescript
+Version: 0.0.1
+Summary: A Typescript handler for mkdocstrings.
+Author-Email: =?utf-8?q?Timoth=C3=A9e_Mazzucotelli?= <dev@pawamoy.fr>
+License: ISC
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://mkdocstrings.github.io/typescript
+Project-URL: Documentation, https://mkdocstrings.github.io/typescript
+Project-URL: Changelog, https://mkdocstrings.github.io/typescript/changelog
+Project-URL: Repository, https://github.com/mkdocstrings/typescript
+Project-URL: Issues, https://github.com/mkdocstrings/typescript/issues
+Project-URL: Discussions, https://github.com/mkdocstrings/typescript/discussions
+Project-URL: Gitter, https://gitter.im/mkdocstrings/typescript
+Project-URL: Funding, https://github.com/sponsors/pawamoy
+Requires-Python: >=3.8
+Requires-Dist: mkdocstrings>=0.24
+Requires-Dist: griffe-typedoc>=0.0
+Description-Content-Type: text/markdown
+
+# mkdocstrings-typescript
+
+[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://mkdocstrings.github.io/typescript/)
+[![gitpod](https://img.shields.io/badge/gitpod-workspace-708FCC.svg?style=flat)](https://gitpod.io/#https://github.com/mkdocstrings/typescript)
+[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#typescript:gitter.im)
+
+A Typescript handler for mkdocstrings. :warning: **Work in progress** :warning:
+
+## Installation
+
+This project is available to sponsors only, through my Insiders program.
+See Insiders [explanation](https://mkdocstrings.github.io/typescript/insiders/)
+and [installation instructions](https://mkdocstrings.github.io/typescript/insiders/installation/).

mkdocstrings_typescript-0.0.1/README.md

@@ -0,0 +1,13 @@
+# mkdocstrings-typescript
+
+[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://mkdocstrings.github.io/typescript/)
+[![gitpod](https://img.shields.io/badge/gitpod-workspace-708FCC.svg?style=flat)](https://gitpod.io/#https://github.com/mkdocstrings/typescript)
+[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#typescript:gitter.im)
+
+A Typescript handler for mkdocstrings. :warning: **Work in progress** :warning:
+
+## Installation
+
+This project is available to sponsors only, through my Insiders program.
+See Insiders [explanation](https://mkdocstrings.github.io/typescript/insiders/)
+and [installation instructions](https://mkdocstrings.github.io/typescript/insiders/installation/).

mkdocstrings_typescript-0.0.1/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[project]
+name = "mkdocstrings-typescript"
+description = "A Typescript handler for mkdocstrings."
+authors = [
+    { name = "Timothée Mazzucotelli", email = "dev@pawamoy.fr" },
+]
+readme = "README.md"
+requires-python = ">=3.8"
+keywords = []
+dynamic = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Documentation",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "mkdocstrings>=0.24",
+    "griffe-typedoc>=0.0",
+]
+version = "0.0.1"
+
+[project.license]
+text = "ISC"
+
+[project.urls]
+Homepage = "https://mkdocstrings.github.io/typescript"
+Documentation = "https://mkdocstrings.github.io/typescript"
+Changelog = "https://mkdocstrings.github.io/typescript/changelog"
+Repository = "https://github.com/mkdocstrings/typescript"
+Issues = "https://github.com/mkdocstrings/typescript/issues"
+Discussions = "https://github.com/mkdocstrings/typescript/discussions"
+Gitter = "https://gitter.im/mkdocstrings/typescript"
+Funding = "https://github.com/sponsors/pawamoy"
+
+[tool.pdm.version]
+source = "scm"
+
+[tool.pdm.build]
+package-dir = "src"
+includes = [
+    "src/mkdocstrings_handlers",
+]
+editable-backend = "editables"
+source-includes = [
+    "share",
+]
+
+[tool.pdm.build.wheel-data]
+data = [
+    { path = "share/**/*", relative-to = "." },
+]

mkdocstrings_typescript-0.0.1/src/mkdocstrings_handlers/typescript/__init__.py

@@ -0,0 +1,5 @@
+"""Typescript handler for mkdocstrings."""
+
+from mkdocstrings_handlers.typescript.handler import get_handler
+
+__all__ = ["get_handler"]

mkdocstrings_typescript-0.0.1/src/mkdocstrings_handlers/typescript/debug.py

@@ -0,0 +1,109 @@
+"""Debugging utilities."""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from dataclasses import dataclass
+from importlib import metadata
+
+
+@dataclass
+class Variable:
+    """Dataclass describing an environment variable."""
+
+    name: str
+    """Variable name."""
+    value: str
+    """Variable value."""
+
+
+@dataclass
+class Package:
+    """Dataclass describing a Python package."""
+
+    name: str
+    """Package name."""
+    version: str
+    """Package version."""
+
+
+@dataclass
+class Environment:
+    """Dataclass to store environment information."""
+
+    interpreter_name: str
+    """Python interpreter name."""
+    interpreter_version: str
+    """Python interpreter version."""
+    interpreter_path: str
+    """Path to Python executable."""
+    platform: str
+    """Operating System."""
+    packages: list[Package]
+    """Installed packages."""
+    variables: list[Variable]
+    """Environment variables."""
+
+
+def _interpreter_name_version() -> tuple[str, str]:
+    if hasattr(sys, "implementation"):
+        impl = sys.implementation.version
+        version = f"{impl.major}.{impl.minor}.{impl.micro}"
+        kind = impl.releaselevel
+        if kind != "final":
+            version += kind[0] + str(impl.serial)
+        return sys.implementation.name, version
+    return "", "0.0.0"
+
+
+def get_version(dist: str = "mkdocstrings-typescript") -> str:
+    """Get version of the given distribution.
+
+    Parameters:
+        dist: A distribution name.
+
+    Returns:
+        A version number.
+    """
+    try:
+        return metadata.version(dist)
+    except metadata.PackageNotFoundError:
+        return "0.0.0"
+
+
+def get_debug_info() -> Environment:
+    """Get debug/environment information.
+
+    Returns:
+        Environment information.
+    """
+    py_name, py_version = _interpreter_name_version()
+    packages = ["mkdocstrings-typescript"]
+    variables = ["PYTHONPATH", *[var for var in os.environ if var.startswith("MKDOCSTRINGS_TYPESCRIPT")]]
+    return Environment(
+        interpreter_name=py_name,
+        interpreter_version=py_version,
+        interpreter_path=sys.executable,
+        platform=platform.platform(),
+        variables=[Variable(var, val) for var in variables if (val := os.getenv(var))],
+        packages=[Package(pkg, get_version(pkg)) for pkg in packages],
+    )
+
+
+def print_debug_info() -> None:
+    """Print debug/environment information."""
+    info = get_debug_info()
+    print(f"- __System__: {info.platform}")
+    print(f"- __Python__: {info.interpreter_name} {info.interpreter_version} ({info.interpreter_path})")
+    print("- __Environment variables__:")
+    for var in info.variables:
+        print(f"  - `{var.name}`: `{var.value}`")
+    print("- __Installed packages__:")
+    for pkg in info.packages:
+        print(f"  - `{pkg.name}` v{pkg.version}")
+
+
+if __name__ == "__main__":
+    print_debug_info()

mkdocstrings_typescript-0.0.1/src/mkdocstrings_handlers/typescript/handler.py

@@ -0,0 +1,171 @@
+"""This module implements a handler for the Typescript language."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar, Mapping, MutableMapping
+
+from mkdocstrings.handlers.base import BaseHandler, CollectorItem
+from mkdocstrings.loggers import get_logger
+
+if TYPE_CHECKING:
+    from markdown import Markdown
+
+
+logger = get_logger(__name__)
+
+
+class TypescriptHandler(BaseHandler):
+    """The Typescript handler class."""
+
+    domain: str = "typescript"
+    """The cross-documentation domain/language for this handler."""
+
+    enable_inventory: bool = False
+    """Whether this handler is interested in enabling the creation of the `objects.inv` Sphinx inventory file."""
+
+    fallback_theme = "material"
+    """The theme to fallback to."""
+
+    fallback_config: ClassVar[dict] = {"fallback": True}
+    """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.
+
+    Option | Type | Description | Default
+    ------ | ---- | ----------- | -------
+    **`show_root_heading`** | `bool` | Show the heading of the object at the root of the documentation tree. | `False`
+    **`show_root_toc_entry`** | `bool` | If the root heading is not shown, at least add a ToC entry for it. | `True`
+    **`heading_level`** | `int` | The initial heading level to use. | `2`
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize the handler.
+
+        Parameters:
+            *args: Passed to the [base handler][mkdocstrings.handlers.base import BaseHandler].
+            **kwargs: Passed to the [base handler][mkdocstrings.handlers.base import BaseHandler].
+        """
+        kwargs.pop("config_file_path", None)
+        super().__init__(*args, **kwargs)
+        self._collected: dict[str, CollectorItem] = {}
+
+    def collect(self, identifier: str, config: MutableMapping[str, Any]) -> CollectorItem:  # noqa: ARG002
+        """Collect data given an identifier and selection configuration.
+
+        In the implementation, you typically call a subprocess that returns JSON, and load that JSON again into
+        a Python dictionary for example, though the implementation is completely free.
+
+        Parameters:
+            identifier: An identifier that was found in a markdown document for which to collect data. For example,
+                in Python, it would be 'mkdocstrings.handlers' to collect documentation about the handlers module.
+                It can be anything that you can feed to the tool of your choice.
+            config: All configuration options for this handler either defined globally in `mkdocs.yml` or
+                locally overridden in an identifier block by the user.
+
+        Returns:
+            Anything you want, as long as you can feed it to the `render` method.
+        """
+        return {"identifier": identifier}
+
+    def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:  # noqa: ARG002
+        """Render a template using provided data and configuration options.
+
+        Parameters:
+            data: The data to render that was collected above in `collect()`.
+            config: All configuration options for this handler either defined globally in `mkdocs.yml` or
+                locally overridden in an identifier block by the user.
+
+        Returns:
+            The rendered template as HTML.
+        """
+        return (
+            f"<i><b><code>::: {data['identifier']}</code></b><br>The public version of mkdocstrings-typescript is a no-op "
+            "and exist only to allow building docs without errors. Please rely on docs preview in CI.</i>"
+        )
+
+    def update_env(self, md: Markdown, config: dict) -> None:
+        """Update the Jinja environment with any custom settings/filters/options for this handler.
+
+        Parameters:
+            md: The Markdown instance. Useful to add functions able to convert Markdown into the environment filters.
+            config: Configuration options for `mkdocs` and `mkdocstrings`, read from `mkdocs.yml`. See the source code
+                of [mkdocstrings.plugin.MkdocstringsPlugin.on_config][] to see what's in this dictionary.
+        """
+        super().update_env(md, config)  # Add some mkdocstrings default filters such as highlight and convert_markdown
+        self.env.trim_blocks = True
+        self.env.lstrip_blocks = True
+        self.env.keep_trailing_newline = False
+
+
+def get_handler(
+    theme: str,
+    custom_templates: str | None = None,
+    config_file_path: str | None = None,
+    **config: Any,  # noqa: ARG001
+) -> TypescriptHandler:
+    """Simply return an instance of `TypescriptHandler`.
+
+    Parameters:
+        theme: The theme to use when rendering contents.
+        custom_templates: Directory containing custom templates.
+        config_file_path: The MkDocs configuration file path.
+        **config: Configuration passed to the handler.
+
+    Returns:
+        An instance of the handler.
+    """
+    return TypescriptHandler(
+        handler="typescript",
+        theme=theme,
+        custom_templates=custom_templates,
+        config_file_path=config_file_path,
+    )

mkdocstrings-typescript-0.0.0/PKG-INFO

@@ -1,15 +0,0 @@
-Metadata-Version: 2.1
-Name: mkdocstrings-typescript
-Version: 0.0.0
-Summary: A TypeScript handler for mkdocstrings. Available to sponsors only.
-Author-email: Timothée Mazzucotelli <pawamoy@pm.me>
-Classifier: Development Status :: 1 - Planning
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-
-# mkdocstrings-typescript
-
-A TypeScript handler for mkdocstrings.
-
-This project is currently available to [sponsors](https://github.com/sponsors/pawamoy) only.
-See https://pawamoy.github.io/mkdocstrings-typescript/insiders.

mkdocstrings-typescript-0.0.0/README.md

@@ -1,6 +0,0 @@
-# mkdocstrings-typescript
-
-A TypeScript handler for mkdocstrings.
-
-This project is currently available to [sponsors](https://github.com/sponsors/pawamoy) only.
-See https://pawamoy.github.io/mkdocstrings-typescript/insiders.

mkdocstrings-typescript-0.0.0/mkdocstrings_typescript.egg-info/PKG-INFO

@@ -1,15 +0,0 @@
-Metadata-Version: 2.1
-Name: mkdocstrings-typescript
-Version: 0.0.0
-Summary: A TypeScript handler for mkdocstrings. Available to sponsors only.
-Author-email: Timothée Mazzucotelli <pawamoy@pm.me>
-Classifier: Development Status :: 1 - Planning
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-
-# mkdocstrings-typescript
-
-A TypeScript handler for mkdocstrings.
-
-This project is currently available to [sponsors](https://github.com/sponsors/pawamoy) only.
-See https://pawamoy.github.io/mkdocstrings-typescript/insiders.

mkdocstrings-typescript-0.0.0/mkdocstrings_typescript.egg-info/SOURCES.txt

@@ -1,6 +0,0 @@
-README.md
-pyproject.toml
-mkdocstrings_typescript.egg-info/PKG-INFO
-mkdocstrings_typescript.egg-info/SOURCES.txt
-mkdocstrings_typescript.egg-info/dependency_links.txt
-mkdocstrings_typescript.egg-info/top_level.txt

mkdocstrings-typescript-0.0.0/mkdocstrings_typescript.egg-info/dependency_links.txt

@@ -1 +0,0 @@
-

mkdocstrings-typescript-0.0.0/mkdocstrings_typescript.egg-info/top_level.txt

@@ -1 +0,0 @@
-

mkdocstrings-typescript-0.0.0/pyproject.toml

@@ -1,8 +0,0 @@
-[project]
-name = "mkdocstrings-typescript"
-version = "0.0.0"
-description = "A TypeScript handler for mkdocstrings. Available to sponsors only."
-authors = [{name = "Timothée Mazzucotelli", email = "pawamoy@pm.me"}]
-readme = "README.md"
-requires-python = ">=3.8"
-classifiers = ["Development Status :: 1 - Planning"]

mkdocstrings-typescript-0.0.0/setup.cfg

@@ -1,4 +0,0 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-