API Documentation

Great Docs automatically discovers and documents your package’s public API. This guide explains how discovery works and how to customize the output.

How Discovery Works

When you run great-docs init or great-docs build, Great Docs:

Finds your package – Looks in standard locations (src/, python/, project root)
Uses static analysis – Analyzes your code with griffe without importing it
Discovers public names – Finds all non-private names (not starting with _)
Introspects submodules – Drills into exported modules to discover their classes, functions, and constants
Categorizes items – Classifies every export into one of 13 object types
Generates configuration – Creates API reference sections in _quarto.yml

Static Analysis Benefits

Great Docs uses static analysis rather than importing your package. This means:

No side effects – Your code isn’t executed during discovery
No import errors – Missing dependencies won’t break documentation
Faster discovery – No need to set up a complete environment
Safer – Works even if your package has complex initialization

What Gets Documented

By default, Great Docs documents everything it discovers in your package’s public API. Each export is classified into one of the following object types:

Class-like Types

Classes – Regular public classes with their methods
Dataclasses – Classes decorated with @dataclass
Abstract Classes – Classes inheriting from ABC or using ABCMeta
Protocols – Structural typing protocols (typing.Protocol subclasses)
Enumerations – Enum subclasses
Exceptions – Exception and BaseException subclasses
Named Tuples – NamedTuple definitions
Typed Dicts – TypedDict definitions

Function-like Types

Functions – Synchronous public functions
Async Functions – Functions defined with async def

Data Types

Constants – Module-level constants and data
Type Aliases – Type alias definitions (including TypeVar)

Other

Other – Anything that doesn’t fit the above categories

Each type is placed into its own section in the generated reference and receives a distinct visual badge (see Type Labels below).

Exclusion Rules

Some names are automatically excluded:

# These are auto-excluded:
main        # CLI entry points
cli
version     # Version metadata
VERSION
core        # Internal modules
utils
helpers
logger      # Logging
log

To exclude additional names from init and scan:

great-docs.yml

exclude:
  - InternalHelper
  - deprecated_function

Note: Once you have a reference config in great-docs.yml, you control exactly what gets documented by listing items there. The exclude setting only affects what great-docs init discovers when generating your initial config.

Smart Method Handling

Large classes with many methods can create overwhelming documentation. Great Docs handles this intelligently by separating methods into their own pages when a class exceeds a threshold.

Small Classes (≤5 methods)

Methods are documented inline on the class page:

_quarto.yml

sections:
  - title: Classes
    contents:
      - MySmallClass  # Methods shown inline

Large Classes (>5 methods)

Methods get their own section with individual pages:

_quarto.yml

sections:
  - title: Classes
    contents:
      - name: MyLargeClass
        members: []  # Suppresses inline methods

  - title: MyLargeClass Methods
    desc: Methods for the MyLargeClass class
    contents:
      - MyLargeClass.method_one
      - MyLargeClass.method_two
      # ... all methods listed individually

This creates better navigation for classes with many methods.

API Organization

Default Sections

Great Docs creates sections automatically based on what it discovers. Only non-empty sections appear:

Section	Description
Classes	Regular public classes
Dataclasses	Data-holding classes
Abstract Classes	Abstract base classes
Protocols	Structural typing protocols
Enumerations	Enum types
Exceptions	Exception classes
Named Tuples	NamedTuple types
Typed Dicts	TypedDict types
Functions	Synchronous functions
Async Functions	Asynchronous functions (`async def`)
Constants	Module-level constants and data
Type Aliases	Type alias definitions
Other	Additional exports
[ClassName] Methods	Created for classes with >5 methods

A typical package might only produce a few of these (e.g., Classes, Functions, and Constants). The section structure is automatically tailored to your package’s contents.

You’re encouraged to customize the organization using the reference config in great-docs.yml to create sections that better reflect your package’s domain.

Custom Organization with `reference` Config

You can explicitly control the API reference structure in great-docs.yml:

great-docs.yml

reference:
  - title: User Management
    desc: Functions for managing users
    contents:
      - create_user
      - delete_user
      - update_user

  - title: Authentication
    desc: Functions for authentication
    contents:
      - login
      - logout

Items appear in the order listed within each section. This explicit configuration gives you complete control over how your API documentation is organized.

Custom Title and Description

You can customize the heading and introductory text of the API reference page using the title and desc keys:

great-docs.yml

reference:
  title: "API Docs"
  desc: >
    Welcome to the API documentation. This reference covers all public
    classes and functions available in the package.

When set, the title replaces the default “Reference” heading on the API index page and in the navigation bar. The desc text appears as a paragraph immediately below the heading, providing context before the section listings.

Without explicit sections, sections are auto-generated from your package’s public API. You can also combine title/desc with explicit section ordering using a sections key:

great-docs.yml

reference:
  title: "API Reference"
  desc: "Complete reference for all public symbols."
  sections:
    - title: Core
      desc: Primary classes
      contents:
        - MyClass
        - Config
    - title: Utilities
      desc: Helper functions
      contents:
        - format_output
        - parse_input

If neither title nor desc is set, the page heading defaults to “Reference” with no introductory text.

Controlling Method Documentation

By default, class methods are documented inline on the class page. To exclude methods from documentation (for example, if you want to document them separately elsewhere), use members: false:

great-docs.yml

reference:
  - title: Core Classes
    desc: Main classes for the package
    contents:
      - name: MyClass
        members: false       # Don't document methods here
      - SimpleClass          # Methods documented inline (default)

  - title: MyClass Methods
    desc: Methods for the MyClass class
    contents:
      - MyClass.method1
      - MyClass.method2

When members: false is set, only the class itself is documented. You can then place individual methods wherever you want in your reference structure.

Excluding Items with `exclude`

To exclude items from documentation, add them to the exclude list in great-docs.yml:

great-docs.yml

exclude:
  - internal_helper
  - deprecated_function

Items in the exclude list won’t appear when running great-docs init or great-docs scan, and won’t be documented even if discovered.

Source Code Links

Great Docs automatically adds “source” links to each documented item, pointing to the exact line numbers on GitHub.

How It Works

Great Docs detects your GitHub repository from pyproject.toml or .git
For each documented item, it finds the source file and line numbers
Links are generated pointing to github.com/owner/repo/blob/branch/file#L1-L10

Configuration

great-docs.yml

source:
  # Use a specific branch (default: auto-detected)
  branch: main

  # Disable source links
  enabled: false

Submodule Introspection

When your package exports submodules (e.g., dateutil.parser, dateutil.tz), Great Docs automatically drills into each module to discover its public classes, functions, and constants. This means you can list a module name in your reference config and Great Docs will expand it into all of its individual members.

For example, if your package exports a parser submodule containing a parse() function, a parser class, and a ParserError exception, writing:

great-docs.yml

reference:
  - title: Parser
    desc: Date string parsing
    contents:
      - parser

will automatically expand to document parser.parse, parser.parser, parser.ParserError, and all other public members of the parser module. Each member is classified into the correct object type and receives appropriate visual treatment.

This is particularly useful for packages like dateutil that organize their API into topical submodules rather than exporting everything from the top-level __init__.py.

Cross-Referencing

Great Docs includes a linking system (GDLS) that automatically creates clickable navigation between your API reference pages. It supports %seealso directives in docstrings, inline interlinks using Markdown syntax, and automatic code-to-link conversion for inline code that matches documented symbols.

See Cross-Referencing for the full guide to all linking features.

Sphinx & RST Cleanup

Docstrings sometimes contain Sphinx cross-reference roles (like :py:exc:`ValueError`) or RST directives (like .. versionadded:: 2.0). These constructs are designed for Sphinx but appear as literal text in non-Sphinx renderers.

Great Docs automatically translates these into clean, styled HTML during the post-render step.

Sphinx Cross-Reference Roles

Sphinx roles like :py:class:, :func:, and :exc: are converted into plain inline code formatting. For example, :py:exc:`ValueError` becomes ValueError, and :py:class:`datetime.datetime` becomes datetime.datetime. Function and method roles automatically receive trailing () to indicate they are callable, so :func:`my_function` renders as my_function() and :meth:`MyClass.run` renders as MyClass.run().

RST Admonition & Version Directives

RST directives are converted into styled callout boxes with appropriate icons and colors:

Directive	Appearance
`.. versionadded:: 2.0`	🆕 Green callout: “Added in version 2.0”
`.. versionchanged:: 3.1`	🔄 Blue callout: “Changed in version 3.1”
`.. deprecated:: 2.6`	⚠️ Red callout: “Deprecated since version 2.6”
`.. note:: ...`	ℹ️ Blue callout
`.. warning:: ...`	⚠️ Amber callout
`.. tip:: ...`	💡 Green callout
`.. danger:: ...`	🚨 Red callout
`.. important:: ...`	❗ Orange callout

Optional description text after the version number is preserved in the callout body.

Visual Enhancements

Great Docs applies consistent styling to your API documentation, making it easier to scan and understand at a glance.

Type Labels

Each documented item displays a colored badge indicating its object type:

Type	Color	Used For
class	Indigo	Classes, dataclasses, protocols, ABCs, named tuples, typed dicts
exception	Red	Exception classes
enum	Indigo	Enum types
function	Violet	Functions (shown with trailing `()`)
method	Cyan	Class methods (shown as `Class.method()`)
constant	Amber	Module-level constants
type alias	Green	Type alias definitions
other	Gray	Uncategorized exports

Great Docs uses a metadata file (_object_types.json) generated during the build to determine the correct badge for each item. This ensures accurate classification even for edge cases like constants that start with an uppercase letter or functions named after classes.

Code Styling

The documentation applies careful typography to code elements throughout. Function signatures use monospace fonts for clarity, and type annotations are formatted to be easily readable. Parameter lists have improved spacing that makes long signatures scannable. Code blocks benefit from enhanced syntax highlighting that matches the overall site theme. Together, these refinements make technical content more approachable.

Responsive Design

API documentation needs to work on devices of all sizes, from large desktop monitors to phones. Great Docs optimizes the layout for each screen size with mobile-friendly navigation that adapts to touch interactions. The sidebar becomes collapsible on smaller screens, and typography scales appropriately to remain readable. Whether you’re at your desk or reviewing docs on your phone during a commute, the experience remains consistent.

Sidebar Filter

For packages with many exports, navigating the sidebar can become cumbersome. Great Docs addresses this with a built-in search filter that appears automatically when your API has 20 or more items.

The filter provides instant results as you type, narrowing down the sidebar to show only matching items. A count indicator shows how many items match your search out of the total. The section structure is preserved during filtering, so you maintain context about where items live in your API hierarchy.

You can customize when the filter appears in your great-docs.yml:

great-docs.yml

sidebar_filter:
  enabled: true
  min_items: 15   # Show filter with 15+ items

Set enabled: false to disable it entirely, or adjust min_items to change the threshold.

Refreshing API Documentation

When your package’s API changes, rebuild with:

Terminal

great-docs build

This automatically re-discovers exports and updates the configuration.

For faster builds when only documentation content changed (not API):

Terminal

great-docs build --no-refresh

Next Steps

Cross-Referencing covers the full linking system (GDLS) for connecting API pages
CLI Documentation covers Click CLI documentation
User Guides explains how to add narrative documentation
Configuration covers all great-docs.yml options