griffe2md 1.0.0__tar.gz

griffe2md-1.0.0/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.

griffe2md-1.0.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.1
+Name: griffe2md
+Version: 1.0.0
+Summary: Output API docs to Markdown using Griffe.
+Author-Email: Timothée Mazzucotelli <pawamoy@pm.me>
+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: Topic :: Documentation
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://mkdocstrings.github.io/griffe2md
+Project-URL: Documentation, https://mkdocstrings.github.io/griffe2md
+Project-URL: Changelog, https://mkdocstrings.github.io/griffe2md/changelog
+Project-URL: Repository, https://github.com/mkdocstrings/griffe2md
+Project-URL: Issues, https://github.com/mkdocstrings/griffe2md/issues
+Project-URL: Discussions, https://github.com/mkdocstrings/griffe2md/discussions
+Project-URL: Gitter, https://gitter.im/mkdocstrings/griffe2md
+Project-URL: Funding, https://github.com/sponsors/pawamoy
+Requires-Python: >=3.8
+Requires-Dist: griffe>=0.36.0
+Requires-Dist: jinja2>=3.1.2
+Requires-Dist: mdformat>=0.7.16
+Description-Content-Type: text/markdown
+
+# griffe2md
+
+[![ci](https://github.com/mkdocstrings/griffe2md/workflows/ci/badge.svg)](https://github.com/mkdocstrings/griffe2md/actions?query=workflow%3Aci)
+[![documentation](https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat)](https://mkdocstrings.github.io/griffe2md/)
+[![pypi version](https://img.shields.io/pypi/v/griffe2md.svg)](https://pypi.org/project/griffe2md/)
+[![gitpod](https://img.shields.io/badge/gitpod-workspace-blue.svg?style=flat)](https://gitpod.io/#https://github.com/mkdocstrings/griffe2md)
+[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#griffe2md:gitter.im)
+
+Output API docs to Markdown using Griffe.
+
+## Installation
+
+With `pip`:
+
+```bash
+pip install griffe2md
+```
+
+With [`pipx`](https://github.com/pipxproject/pipx):
+
+```bash
+python3.8 -m pip install --user pipx
+pipx install griffe2md
+```
+
+## Usage
+
+Simply call `griffe2md` with a package name, or the path to a package folder:
+
+```bash
+griffe2md markdown
+griffe2md path/to/my/src/package
+```
+
+Use the `-o`, `--output` option to write to a file instead of standard output:
+
+```bash
+griffe2md markdown -o markdown.md
+```

griffe2md-1.0.0/README.md

@@ -0,0 +1,39 @@
+# griffe2md
+
+[![ci](https://github.com/mkdocstrings/griffe2md/workflows/ci/badge.svg)](https://github.com/mkdocstrings/griffe2md/actions?query=workflow%3Aci)
+[![documentation](https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat)](https://mkdocstrings.github.io/griffe2md/)
+[![pypi version](https://img.shields.io/pypi/v/griffe2md.svg)](https://pypi.org/project/griffe2md/)
+[![gitpod](https://img.shields.io/badge/gitpod-workspace-blue.svg?style=flat)](https://gitpod.io/#https://github.com/mkdocstrings/griffe2md)
+[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#griffe2md:gitter.im)
+
+Output API docs to Markdown using Griffe.
+
+## Installation
+
+With `pip`:
+
+```bash
+pip install griffe2md
+```
+
+With [`pipx`](https://github.com/pipxproject/pipx):
+
+```bash
+python3.8 -m pip install --user pipx
+pipx install griffe2md
+```
+
+## Usage
+
+Simply call `griffe2md` with a package name, or the path to a package folder:
+
+```bash
+griffe2md markdown
+griffe2md path/to/my/src/package
+```
+
+Use the `-o`, `--output` option to write to a file instead of standard output:
+
+```bash
+griffe2md markdown -o markdown.md
+```

griffe2md-1.0.0/pyproject.toml

@@ -0,0 +1,113 @@
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[project]
+name = "griffe2md"
+description = "Output API docs to Markdown using Griffe."
+authors = [
+    { name = "Timothée Mazzucotelli", email = "pawamoy@pm.me" },
+]
+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",
+    "Topic :: Documentation",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "griffe>=0.36.0",
+    "jinja2>=3.1.2",
+    "mdformat>=0.7.16",
+]
+version = "1.0.0"
+
+[project.license]
+text = "ISC"
+
+[project.urls]
+Homepage = "https://mkdocstrings.github.io/griffe2md"
+Documentation = "https://mkdocstrings.github.io/griffe2md"
+Changelog = "https://mkdocstrings.github.io/griffe2md/changelog"
+Repository = "https://github.com/mkdocstrings/griffe2md"
+Issues = "https://github.com/mkdocstrings/griffe2md/issues"
+Discussions = "https://github.com/mkdocstrings/griffe2md/discussions"
+Gitter = "https://gitter.im/mkdocstrings/griffe2md"
+Funding = "https://github.com/sponsors/pawamoy"
+
+[project.scripts]
+griffe2md = "griffe2md.cli:main"
+
+[tool.pdm]
+plugins = [
+    "pdm-multirun",
+]
+
+[tool.pdm.version]
+source = "scm"
+
+[tool.pdm.build]
+package-dir = "src"
+editable-backend = "editables"
+
+[tool.pdm.dev-dependencies]
+duty = [
+    "duty>=0.10",
+]
+ci-quality = [
+    "griffe2md[duty,docs,quality,typing,security]",
+]
+ci-tests = [
+    "griffe2md[duty,tests]",
+]
+docs = [
+    "black>=23.9",
+    "markdown-callouts>=0.3",
+    "markdown-exec>=1.7",
+    "mkdocs>=1.5",
+    "mkdocs-coverage>=1.0",
+    "mkdocs-gen-files>=0.5",
+    "mkdocs-git-committers-plugin-2>=1.2",
+    "mkdocs-literate-nav>=0.6",
+    "mkdocs-material>=9.4",
+    "mkdocs-minify-plugin>=0.7",
+    "mkdocstrings[python]>=0.23",
+    "tomli>=2.0; python_version < '3.11'",
+]
+maintain = [
+    "black>=23.9",
+    "blacken-docs>=1.16",
+    "git-changelog>=2.3",
+]
+quality = [
+    "ruff>=0.0",
+]
+tests = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "pytest-randomly>=3.15",
+    "pytest-xdist>=3.3",
+]
+typing = [
+    "mypy>=1.5",
+    "types-markdown>=3.5",
+    "types-pyyaml>=6.0",
+]
+security = [
+    "safety>=2.3",
+]

griffe2md-1.0.0/src/griffe2md/__init__.py

@@ -0,0 +1,8 @@
+"""griffe2md package.
+
+Output API docs to Markdown using Griffe.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

griffe2md-1.0.0/src/griffe2md/cli.py

@@ -0,0 +1,61 @@
+"""Module that contains the command line application."""
+
+# Why does this file exist, and why not put this in `__main__`?
+#
+# You might be tempted to import things from `__main__` later,
+# but that will cause problems: the code will get executed twice:
+#
+# - When you run `python -m griffe2md` python will execute
+#   `__main__.py` as a script. That means there won't be any
+#   `griffe2md.__main__` in `sys.modules`.
+# - When you import `__main__` it will get executed again (as a module) because
+#   there's no `griffe2md.__main__` in `sys.modules`.
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from griffe2md import debug
+from griffe2md.main import write_package_docs
+
+
+class _DebugInfo(argparse.Action):
+    def __init__(self, nargs: int | str | None = 0, **kwargs: Any) -> None:
+        super().__init__(nargs=nargs, **kwargs)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
+        debug.print_debug_info()
+        sys.exit(0)
+
+
+def get_parser() -> argparse.ArgumentParser:
+    """Return the CLI argument parser.
+
+    Returns:
+        An argparse parser.
+    """
+    parser = argparse.ArgumentParser(prog="griffe2md")
+    parser.add_argument("package", help="The package to output Markdown docs for.")
+    parser.add_argument("-o", "--output", default=None, help="File to write to. Default: stdout.")
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {debug.get_version()}")
+    parser.add_argument("--debug-info", action=_DebugInfo, help="Print debug information.")
+    return parser
+
+
+def main(args: list[str] | None = None) -> int:
+    """Run the main program.
+
+    This function is executed when you type `griffe2md` or `python -m griffe2md`.
+
+    Parameters:
+        args: Arguments passed from the command line.
+
+    Returns:
+        An exit code.
+    """
+    parser = get_parser()
+    opts = parser.parse_args(args=args)
+    write_package_docs(opts.package, output=opts.output)
+    return 0

griffe2md-1.0.0/src/griffe2md/debug.py

@@ -0,0 +1,106 @@
+"""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."""
+    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 = "griffe2md") -> 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 = ["griffe2md"]
+    variables = ["PYTHONPATH", *[var for var in os.environ if var.startswith("GRIFFE2MD")]]
+    return Environment(
+        interpreter_name=py_name,
+        interpreter_version=py_version,
+        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}")
+    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()

griffe2md-1.0.0/src/griffe2md/main.py

@@ -0,0 +1,159 @@
+"""Main function of the program."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import IO, TYPE_CHECKING
+
+import mdformat
+from griffe.docstrings import Parser
+from griffe.loader import GriffeLoader
+from jinja2 import Environment, FileSystemLoader
+
+from griffe2md import rendering
+
+if TYPE_CHECKING:
+    from griffe import Object
+
+
+def _output(text: str, to: IO | str | None = None) -> None:
+    if isinstance(to, str):
+        with open(to, "w") as output:
+            output.write(text)
+    else:
+        if to is None:
+            to = sys.stdout
+        to.write(text)
+
+
+def prepare_context(obj: Object, config: dict | None = None) -> dict:
+    """Prepare Jinja context.
+
+    Parameters:
+        obj: A Griffe object.
+        config: The configuration options.
+
+    Returns:
+        The Jinja context.
+    """
+    config = config or dict(rendering.default_config)
+    if config["filters"]:
+        config["filters"] = [(re.compile(filtr.lstrip("!")), filtr.startswith("!")) for filtr in config["filters"]]
+
+    heading_level = config["heading_level"]
+    try:
+        config["members_order"] = rendering.Order(config["members_order"])
+    except ValueError as error:
+        choices = "', '".join(item.value for item in rendering.Order)
+        raise ValueError(
+            f"Unknown members_order '{config['members_order']}', choose between '{choices}'.",
+        ) from error
+
+    summary = config["summary"]
+    if summary is True:
+        config["summary"] = {
+            "attributes": True,
+            "functions": True,
+            "classes": True,
+            "modules": True,
+        }
+    elif summary is False:
+        config["summary"] = {
+            "attributes": False,
+            "functions": False,
+            "classes": False,
+            "modules": False,
+        }
+    else:
+        config["summary"] = {
+            "attributes": summary.get("attributes", False),
+            "functions": summary.get("functions", False),
+            "classes": summary.get("classes", False),
+            "modules": summary.get("modules", False),
+        }
+
+    return {
+        "config": config,
+        obj.kind.value: obj,
+        "heading_level": heading_level,
+        "root": True,
+    }
+
+
+def prepare_env(env: Environment | None = None) -> Environment:
+    """Prepare Jinja environment.
+
+    Parameters:
+        env: A Jinja environment.
+
+    Returns:
+        The Jinja environment.
+    """
+    env = env or Environment(
+        autoescape=False,  # noqa: S701
+        loader=FileSystemLoader([Path(__file__).parent / "templates"]),
+        auto_reload=False,
+    )
+    env.filters["any"] = rendering.do_any
+    env.filters["heading"] = rendering.do_heading
+    env.filters["as_attributes_section"] = rendering.do_as_attributes_section
+    env.filters["as_classes_section"] = rendering.do_as_classes_section
+    env.filters["as_functions_section"] = rendering.do_as_functions_section
+    env.filters["as_modules_section"] = rendering.do_as_modules_section
+    env.filters["filter_objects"] = rendering.do_filter_objects
+    env.filters["format_code"] = rendering.do_format_code
+    env.filters["format_signature"] = rendering.do_format_signature
+    env.filters["format_attribute"] = rendering.do_format_attribute
+    env.filters["order_members"] = rendering.do_order_members
+    env.filters["split_path"] = rendering.do_split_path
+    env.filters["stash_crossref"] = lambda ref, length: ref
+    env.filters["from_private_package"] = rendering.from_private_package
+
+    return env
+
+
+def render_object_docs(obj: Object, config: dict | None = None) -> str:
+    """Render docs for a given object.
+
+    Parameters:
+        obj: The Griffe object to render docs for.
+        config: The rendering configuration.
+
+    Returns:
+        Markdown.
+    """
+    env = prepare_env()
+    context = prepare_context(obj, config)
+    rendered = env.get_template(f"{obj.kind.value}.md.jinja").render(**context)
+    return mdformat.text(rendered)
+
+
+def render_package_docs(package: str, config: dict | None = None) -> str:
+    """Render docs for a given package.
+
+    Parameters:
+        package: The package (name) to render docs for.
+        config: The rendering configuration.
+
+    Returns:
+        Markdown.
+    """
+    config = config or dict(rendering.default_config)
+    parser = config["docstring_style"] and Parser(config["docstring_style"])
+    loader = GriffeLoader(docstring_parser=parser)
+    module = loader.load(package)
+    loader.resolve_aliases(external=True)
+    return render_object_docs(module, config)
+
+
+def write_package_docs(package: str, config: dict | None = None, output: IO | str | None = None) -> None:
+    """Write docs for a given package to a file or stdout.
+
+    Parameters:
+        package: The package to render docs for.
+        config: The rendering configuration.
+        output: The file to write to.
+    """
+    _output(render_package_docs(package, config), to=output)