quartopydoc 0.12.0__py3-none-any.whl

quartodoc/__init__.py

@@ -0,0 +1,30 @@
+"""
+quartopydoc is a package for building delightful python API documentation.
+
+It is a fork of quartodoc by Michael Chow, with formatting customizations and
+extra utilities for working with notebooks.
+"""
+
+# flake8: noqa
+
+from .autosummary import get_function, get_object, Builder
+from .renderers import MdRenderer
+from .inventory import convert_inventory, create_inventory
+from .ast import preview
+from .builder.blueprint import blueprint
+from .builder.collect import collect
+from .layout import Auto
+
+__all__ = (
+    "Auto",
+    "blueprint",
+    "collect",
+    "convert_inventory",
+    "create_inventory",
+    "get_object",
+    "preview",
+    "Builder",
+    "BuilderPkgdown",
+    "BuilderSinglePage",
+    "MdRenderer",
+)

quartodoc/__main__.py

@@ -0,0 +1,283 @@
+import click
+import contextlib
+import os
+import sys
+import time
+import sphobjinv as soi
+import yaml
+import importlib
+from pathlib import Path
+from watchdog.observers import Observer
+from functools import partial
+from watchdog.events import PatternMatchingEventHandler
+from quartodoc import Builder, convert_inventory
+from ._pydantic_compat import BaseModel
+from .interlinks import inventory_from_url
+
+
+def get_package_path(package_name):
+    """
+    Get the path to a package installed in the current environment.
+    """
+    try:
+        lib = importlib.import_module(package_name)
+        return lib.__path__[0]
+    except ModuleNotFoundError:
+        raise ModuleNotFoundError(
+            f"Package {package_name} not found.  Please install it in your environment."
+        )
+
+
+class FileInfo(BaseModel):
+    size: int
+    mtime: float
+    name: str = ""
+
+
+class QuartoDocFileChangeHandler(PatternMatchingEventHandler):
+    """
+    A handler for file changes.
+    """
+
+    # Ignore patterns for the file watcher that are not relevant to the docs
+    py_ignore_patterns = [
+        "*/__pycache__/*",  # These are the compiled python code files which are automatically generated by Python
+        "*/.ipynb_checkpoints/*",  # This directory is created by Jupyter Notebook for auto-saving notebooks
+        "*/.vscode/*",  # If you're using Visual Studio Code, it creates this directory to store settings specific to that project.
+        "*/.idea/*",  # Similar to .vscode/, but for JetBrains IDEs like PyCharm.
+        "*/.git/*",  # i This directory is created by Git. It's not relevant to the docs.
+        "*/venv/*",
+        "*/env/*",
+        "*/.env/*",  # Common names for directories containing a Python virtual environment.
+        "*/.pytest_cache/*",  # This directory is created when you run Pytest.
+        "*/.eggs/*",
+        "*/dist/*",
+        "*/build/*",
+        "*/*.egg-info/*",  # These are typically created when building Python packages with setuptools.
+        "*.pyo",  # These are optimized .pyc files, created when Python is run with the -O flag.
+        "*.pyd",  # This is the equivalent of a .pyc file, but for C extensions on Windows.
+        "*/.mypy_cache/*",  # This directory is created when you run mypy.
+    ]
+
+    def __init__(self, callback):
+        super().__init__(
+            ignore_patterns=self.py_ignore_patterns, ignore_directories=True
+        )
+        self.callback = callback
+        self.old_file_info = FileInfo(size=-1, mtime=-1, name="")
+
+    def get_file_info(self, path: str) -> FileInfo:
+        """
+        Get the file size and modification time.
+        """
+        return FileInfo(
+            size=os.stat(path).st_size, mtime=os.stat(path).st_mtime, name=path
+        )
+
+    def is_diff(self, old: FileInfo, new: FileInfo) -> bool:
+        """
+        Check if a file has changed. Prevents duplicate events from being triggered.
+        """
+        same_nm = old.name == new.name
+        diff_sz = old.size != new.size
+        diff_tm = new.mtime - old.mtime  # wait 1/4 second before triggering
+
+        if (
+            diff_tm < 0.25
+        ):  # if consequetive events are less than 1/4th of a second apart, ignore
+            return False
+        elif same_nm:
+            if diff_sz or diff_tm >= 0.25:
+                return True
+            else:
+                return False
+        else:
+            return True
+
+    def callback_if_diff(self, event):
+        """
+        Call the callback if the file has changed.
+        """
+        new_file_info = self.get_file_info(event.src_path)
+        if self.is_diff(self.old_file_info, new_file_info):
+            self.print_event(event)
+            self.callback()
+        self.old_file_info = new_file_info
+
+    @classmethod
+    def print_event(cls, event):
+        print(f"Rebuilding docs.  Detected: {event.event_type} path : {event.src_path}")
+
+    def on_modified(self, event):
+        self.callback_if_diff(event)
+
+    def on_created(self, event):
+        self.callback_if_diff(event)
+
+
+def _enable_logs():
+    import logging
+
+    root = logging.getLogger("quartodoc")
+    root.setLevel(logging.INFO)
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setLevel(logging.DEBUG)
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+    handler.setFormatter(formatter)
+    root.addHandler(handler)
+
+
+@contextlib.contextmanager
+def chdir(new_dir):
+    prev = os.getcwd()
+    os.chdir(new_dir)
+    try:
+        yield new_dir
+    finally:
+        os.chdir(prev)
+
+
+@click.group()
+def cli():
+    pass
+
+
+@click.command()
+@click.option(
+    "--config",
+    default="_quarto.yml",
+    help="Change the path to the configuration file.  The default is `./_quarto.yml`",
+)
+@click.option(
+    "--filter",
+    nargs=1,
+    default="*",
+    help="Specify the filter to select specific files. The default is '*' which selects all files.",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="If set, prevents new documents from being generated.",
+)
+@click.option(
+    "--watch",
+    is_flag=True,
+    default=False,
+    help="If set, the command will keep running and watch for changes in the package directory.",
+)
+@click.option("--verbose", is_flag=True, default=False, help="Enable verbose logging.")
+def build(config, filter, dry_run, watch, verbose):
+    """
+    Generate API docs based on the given configuration file  (`./_quarto.yml` by default).
+    """
+
+    cfg_path = Path(config).absolute()
+    if not cfg_path.exists():
+        raise FileNotFoundError(
+            f"Configuration file {cfg_path} not found.  Please create one."
+        )
+    if verbose:
+        _enable_logs()
+
+    # allow users to include files like _renderer.py in their quarto docs folder
+    if config != "_quarto.yml":
+        sys.path.append(str(Path(config).parent.absolute()))
+
+    builder = Builder.from_quarto_config(config)
+    doc_build = partial(builder.build, filter=filter)
+
+    if dry_run:
+        pass
+    else:
+        # add current directory to path, and then temporarily switch directories.
+        # this supports the case where a user is depending on the current directory
+        # for imports
+        sys.path.append(os.getcwd())
+        with chdir(Path(config).parent):
+            if watch:
+                pkg_path = get_package_path(builder.package)
+                print(f"Watching {pkg_path} for changes...")
+                observer = Observer()
+                observer._event_queue.maxsize = 1  # the default is 0 which is infinite, and there isn't a way to set this in the constructor
+                event_handler = QuartoDocFileChangeHandler(callback=doc_build)
+                observer.schedule(event_handler, pkg_path, recursive=True)
+                observer.schedule(event_handler, cfg_path, recursive=True)
+                observer.start()
+                try:
+                    while True:
+                        time.sleep(1)
+                except KeyboardInterrupt:
+                    pass
+                finally:
+                    observer.stop()
+                    observer.join()
+            else:
+                doc_build()
+
+
+@click.command(
+    short_help="Generate inventory files that the Quarto "
+    "`interlink` extension can use to auto-link to other docs."
+)
+@click.argument("config", default="_quarto.yml")
+@click.option("--dry-run", is_flag=True, default=False)
+@click.option("--fast", is_flag=True, default=False)
+def interlinks(config, dry_run, fast):
+    """
+    Generate inventory files that the Quarto `interlink` extension can use to
+    auto-link to other docs.
+
+    The files are stored in a cache directory, which defaults to _inv.
+    The Quarto extension `interlinks` will look for these files in the cache
+    and add links to your docs accordingly.
+    """
+
+    # config loading ----
+    cfg = yaml.safe_load(open(config))
+    interlinks = cfg.get("interlinks", {})
+
+    p_root = Path(config).parent
+
+    if not interlinks:
+        print("No interlinks field found in your quarto config. Quitting.")
+        return
+
+    # interlinks config settings ----
+    cache = p_root / "_inv"
+    cfg_fast = interlinks.get("fast", False)
+
+    fast = cfg_fast or fast
+
+    for k, v in interlinks["sources"].items():
+        # don't include user's own docs (users don't need to specify their own docs in
+        # the interlinks config anymore, so this is for backwards compat).
+        if v["url"] == "/":
+            continue
+
+        url = v["url"] + v.get("inv", "objects.inv")
+
+        inv = inventory_from_url(url)
+
+        p_dst = p_root / cache / f"{k}_objects"
+        p_dst.parent.mkdir(exist_ok=True, parents=True)
+
+        if fast:
+            # use sphobjinv to dump inv in txt format
+            df = inv.data_file()
+            soi.writebytes(p_dst.with_suffix(".txt"), df)
+
+        else:
+            # old behavior of converting to custom json format
+            convert_inventory(inv, p_dst.with_suffix(".json"))
+
+
+cli.add_command(build)
+cli.add_command(interlinks)
+
+
+if __name__ == "__main__":
+    cli()

quartodoc/_griffe_compat/__init__.py

@@ -0,0 +1,11 @@
+# flake8: noqa
+
+from griffe import GriffeLoader
+from griffe import ModulesCollection, LinesCollection
+
+from . import dataclasses
+from . import docstrings
+from . import expressions
+
+from griffe import Parser, parse, parse_numpy
+from griffe import AliasResolutionError

quartodoc/_griffe_compat/_generate_stubs.py

@@ -0,0 +1,71 @@
+"""Generate the submodules which import parts of griffe (e.g. dataclasses.py)
+
+This process balances having to import specific objects from griffe, against
+importing everything via the top-level griffe module. It does this by generating
+modules for objects commonly used together in quartodoc.
+
+* dataclasses: represent python objects
+* docstrings: represent python docstrings
+* expressions: represent annotation expressions
+
+Run using: python -m quartodoc._griffe_compat._generate_stubs
+"""
+
+import ast
+import black
+import copy
+import griffe
+import inspect
+from pathlib import Path
+
+
+def fetch_submodule(ast_body, submodule: str):
+    ast_imports = [
+        obj
+        for obj in ast_body
+        if isinstance(obj, ast.ImportFrom) and obj.module == submodule
+    ]
+
+    if len(ast_imports) > 1:
+        raise Exception(f"Found {len(ast_imports)} imports for {submodule}")
+    elif not ast_imports:
+        raise Exception(f"Could not find import for {submodule}")
+
+    return ast_imports[0]
+
+
+def code_for_imports(mod_code: str, submodules: list[str]) -> str:
+    res = []
+    mod = ast.parse(mod_code)
+    for submod in submodules:
+        expr = fetch_submodule(mod.body, submod)
+        expr.module = "griffe"
+        new_expr = copy.copy(expr)
+        new_expr.module = "griffe"
+        res.append(ast.unparse(new_expr))
+
+    return black.format_str(
+        "# flake8: noqa\n\n" + "\n".join(res), mode=black.FileMode()
+    )
+
+
+def generate_griffe_stub(out_path: Path, mod, submodules: list[str]):
+    res = code_for_imports(inspect.getsource(mod), submodules)
+    out_path.write_text(res)
+
+
+MAPPINGS = {
+    "dataclasses": [
+        "griffe._internal.models",
+        "griffe._internal.mixins",
+        "griffe._internal.enumerations",
+    ],
+    "docstrings": ["griffe._internal.docstrings.models"],
+    "expressions": ["griffe._internal.expressions"],
+}
+
+if __name__ == "__main__":
+    for out_name, submodules in MAPPINGS.items():
+        generate_griffe_stub(
+            Path(__file__).parent / f"{out_name}.py", griffe, submodules
+        )

quartodoc/_griffe_compat/dataclasses.py

@@ -0,0 +1,35 @@
+# flake8: noqa
+
+from griffe import (
+    Alias,
+    Attribute,
+    Class,
+    Decorator,
+    Docstring,
+    Function,
+    Module,
+    Object,
+    Parameter,
+    Parameters,
+    TypeAlias,
+    TypeParameter,
+    TypeParameters,
+)
+from griffe import (
+    DelMembersMixin,
+    GetMembersMixin,
+    ObjectAliasMixin,
+    SerializationMixin,
+    SetMembersMixin,
+)
+from griffe import (
+    BreakageKind,
+    DocstringSectionKind,
+    ExplanationStyle,
+    Kind,
+    LogLevel,
+    ObjectKind,
+    ParameterKind,
+    Parser,
+    TypeParameterKind,
+)

quartodoc/_griffe_compat/docstrings.py

@@ -0,0 +1,38 @@
+# flake8: noqa
+
+from griffe import (
+    DocstringAdmonition,
+    DocstringAttribute,
+    DocstringClass,
+    DocstringDeprecated,
+    DocstringElement,
+    DocstringFunction,
+    DocstringModule,
+    DocstringNamedElement,
+    DocstringParameter,
+    DocstringRaise,
+    DocstringReceive,
+    DocstringReturn,
+    DocstringSection,
+    DocstringSectionAdmonition,
+    DocstringSectionAttributes,
+    DocstringSectionClasses,
+    DocstringSectionDeprecated,
+    DocstringSectionExamples,
+    DocstringSectionFunctions,
+    DocstringSectionModules,
+    DocstringSectionOtherParameters,
+    DocstringSectionParameters,
+    DocstringSectionRaises,
+    DocstringSectionReceives,
+    DocstringSectionReturns,
+    DocstringSectionText,
+    DocstringSectionTypeAliases,
+    DocstringSectionTypeParameters,
+    DocstringSectionWarns,
+    DocstringSectionYields,
+    DocstringTypeAlias,
+    DocstringTypeParameter,
+    DocstringWarn,
+    DocstringYield,
+)

quartodoc/_griffe_compat/expressions.py

@@ -0,0 +1,48 @@
+# flake8: noqa
+
+from griffe import (
+    Expr,
+    ExprAttribute,
+    ExprBinOp,
+    ExprBoolOp,
+    ExprCall,
+    ExprCompare,
+    ExprComprehension,
+    ExprConstant,
+    ExprDict,
+    ExprDictComp,
+    ExprExtSlice,
+    ExprFormatted,
+    ExprGeneratorExp,
+    ExprIfExp,
+    ExprInterpolation,
+    ExprJoinedStr,
+    ExprKeyword,
+    ExprLambda,
+    ExprList,
+    ExprListComp,
+    ExprName,
+    ExprNamedExpr,
+    ExprParameter,
+    ExprSet,
+    ExprSetComp,
+    ExprSlice,
+    ExprSubscript,
+    ExprTemplateStr,
+    ExprTuple,
+    ExprUnaryOp,
+    ExprVarKeyword,
+    ExprVarPositional,
+    ExprYield,
+    ExprYieldFrom,
+    get_annotation,
+    get_base_class,
+    get_class_keyword,
+    get_condition,
+    get_expression,
+    safe_get_annotation,
+    safe_get_base_class,
+    safe_get_class_keyword,
+    safe_get_condition,
+    safe_get_expression,
+)

quartodoc/_pydantic_compat.py

@@ -0,0 +1,18 @@
+try:
+    from pydantic.v1 import (
+        BaseModel,
+        Field,
+        Extra,
+        PrivateAttr,
+        ValidationError,
+        validator,
+    )  # noqa
+except ImportError:
+    from pydantic import (  # noqa
+        BaseModel,
+        Field,
+        Extra,
+        PrivateAttr,
+        ValidationError,
+        validator,
+    )