DOCSEARCHbyAlgolia
Submit Docs

quartodoc

repository·main·Indexed 42 days ago

https://github.com/machow/quartodoc

A tool for generating Python package API reference documentation using Markdown and Quarto. It serves as a modern alternative to Sphinx, providing a Builder engine to automate the creation of .qmd files, index pages, and Sphinx-compatible inventory files for cross-referencing.

Tokens
8.1K
Snippets
35
Records
43
Agent score
54%

What's inside quartodoc

  3. Install quartodoc

    main

    You can install quartodoc via pip or directly from the GitHub repository.

    Important: You must have Quarto installed on your system before using quartodoc to generate documentation.

    python -m pip install quartodoc

    Or from GitHub

    python -m pip install git+https://github.com/machow/quartodoc.git

  4. Available Builder Styles

    main

    The Builder class uses a registry system to support different documentation layouts via the style parameter. Currently supported styles include:

    • pkgdown: Builds an API in the style of the R pkgdown package (multiple pages).
    • single-page: Embeds all API documentation onto a single large page.

  5. Use cross-reference links in documentation

    main

    Quartodoc allows you to create cross-reference links to Python objects (functions, classes, modules, etc.) using a specific syntax. This enables users to click a name in the documentation and be taken to the corresponding reference section.

    • To link to a function: [](:function:name)
    • To link to a class or other object: [](full.path.to.Object)
    [](:function:`print`)

[](`dascore.clients.dirspool.DirectorySpool`)

  6. Load and inspect a Sphinx inventory file in Python

    main

    To programmatically access a Sphinx inventory file (typically objects.inv), use sphinx.util.inventory.InventoryFile.load. This allows you to look up object locations, versions, and URLs within the inventory.

    Once loaded, the InventoryFile object behaves like a dictionary where keys are domain/type identifiers (e.g., py:function) and values are mappings of object names to their metadata tuples.

    from sphinx.util.inventory import InventoryFile
from os import path

SQLALCHEMY_DOCS_URL = "https://docs.sqlalchemy.org/"
SQLALCHEMY_INV_URL = f"{SQLALCHEMY_DOCS_URL}/objects.inv"

# Load the inventory file
with open("objects_sqla.inv", "rb") as f:
    inv = InventoryFile.load(f, SQLALCHEMY_DOCS_URL, path.join)

# List available domains/types
print(list(inv))

# Access specific object metadata
# Returns: (Project Name, Version, URL, Status)
print(inv["py:function"]["sqlalchemy.create_engine"])

  7. Group documentation with Interlaced

    main

    The Interlaced element is used to group a collection of objects where their documentation (signatures, examples, etc.) is interleaved rather than listed as complete blocks for each object. This is useful for presenting related items together.

    Attributes:

    • kind: Fixed to "interlaced".
    • package (Union[str, None, MISSING]): If specified, object lookups are relative to this path.
    • contents (list[Union[Auto, Doc, _AutoDefault]]): The list of objects to interlace. Note that Interlaced cannot contain Page or Section elements.

  8. Fetch a Griffe object with get_object()

    main

    Use get_object() to retrieve a Griffe object representing a Python entity (module, class, function, etc.) using an import path. The path should follow the format module:object (e.g., quartodoc:MdRenderer.render).

    Key parameters:

    • path: The import path.
    • parser: The docstring parser to use ("google", "sphinx", or "numpy"). Defaults to "numpy".
    • load_aliases: If True, it will attempt to load modules for aliases imported from other modules.
    • dynamic: If True, it uses dynamic import to find the target. This is useful if docstrings are set at runtime rather than being hard-coded in the source.

    Note: The object_name parameter is deprecated.

    from quartodoc.autosummary import get_object

# Fetch a specific method
obj = get_object("quartodoc:get_object")

# Fetch a module
mod = get_object("quartodoc")

  9. Build API documentation with build()

    main

    Call build() on a Builder instance to execute the documentation generation pipeline. The pipeline performs the following steps:

    1. Blueprint Generation: Creates a layout of the documentation.
    2. Collection: Gathers pages and inventory items.
    3. Index Writing: Generates the main API index page.
    4. Page Rendering: Writes individual .qmd files for each documented object.
    5. Inventory Creation: Generates a Sphinx-compatible inventory file.
    6. Sidebar/CSS Writing: (Optional) Writes the sidebar configuration and CSS files.

    Filtering

    You can pass a filter string (supporting * wildcards) to build() to only write documentation for objects matching a specific pattern (e.g., build(filter="MyClass*")).

    builder = Builder(package="my_pkg", sections=sections)
# Build everything
builder.build()

# Build only objects matching a pattern
builder.build(filter="utils.*")

  10. Manage and lookup cross-references with `Inventories`

    main

    The Inventories class acts as a registry for EnhancedItem objects (the items found within inventory files). It allows you to perform lookups to resolve a Ref into a specific URI.

    Key methods:

    • from_items(items): Create an Inventories instance from a list of EnhancedItem objects.
    • lookup_reference(ref): Resolves a Ref object to its corresponding EnhancedItem. Raises InvLookupError if the reference is not found or is ambiguous.
    • ref_to_anchor(ref, text): Converts a reference string or Ref object into a Link object containing the resolved URL and display text.
    from quartodoc.interlinks import Inventories, EnhancedItem, Ref

# Setup items
item = EnhancedItem.make_simple('my_inv', 'https://example.com/api', 'my_func')
invs = Inventories.from_items([item])

# Resolve a reference
link = invs.ref_to_anchor("my_func")
print(link.url) # https://example.com/api/my_func.html

  11. Fetch a function with get_function()

    main

    A specialized version of get_object specifically for retrieving functions within a module.

    from quartodoc.autosummary import get_function

# Fetch the function 'get_function' from the 'quartodoc' module
func = get_function("quartodoc", "get_function")

  12. Convert references to Pandoc elements

    main

    If you are working with Pandoc-style representations (where backticks might be encoded as %60), use pandoc_ref_to_anchor.

    Unlike ref_to_anchor, this method:

    1. Handles %60 as a backtick.
    2. Uses warnings.warn instead of raising exceptions if a lookup fails.
    3. Returns an Unchanged object if the string doesn't look like a reference, or a Code object if the lookup fails, ensuring the document structure remains intact.
    from quartodoc.interlinks import Inventories

# Assuming invs is an initialized Inventories instance
# This will return a Link, Code, or Unchanged object
element = invs.pandoc_ref_to_anchor("%60my_func%60", "my_func")