API Documentation

Most Python packages need an API reference, but writing one by hand is tedious and keeping it in sync with code changes is even harder. Great Docs takes care of both: it automatically discovers your package’s public API through static analysis, classifies every export by type, and generates a complete, styled reference section. You can ship a polished API reference without writing a single docstring page yourself, and as your code evolves the documentation stays up to date.

This page explains how discovery works, what gets documented, and how to customize the result.

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

The entire pipeline runs in seconds and produces a fully structured reference. You don’t need to maintain a manifest of your public symbols; Great Docs figures it out from your code.

To preview what Great Docs will find without generating any files, run great-docs scan in your project directory. This lists every discovered export grouped by type, and marks which items are already included in your reference config. Add --verbose to see individual methods on each class.

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

Because discovery never executes your code, you can generate documentation in CI environments, containers, or any machine where your package’s runtime dependencies aren’t installed.

What Gets Documented

By default, Great Docs documents everything it discovers in your package’s public API. These discovered items are the package’s documentable objects: any public class, function, constant, or type alias that Great Docs can identify through static analysis. Each documentable object is classified into one of the following 13 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

Not everything in your package’s namespace belongs in the API reference. Internal wiring like CLI entry points, logging setup, and utility modules are implementation details that would clutter the documentation without helping users. Great Docs automatically excludes a set of common names that almost never represent public API:

# 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, add them to the exclude list in great-docs.yml:

great-docs.yml

exclude:
  - InternalHelper
  - deprecated_function

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. Between the built-in exclusions and the explicit list, you can keep the reference focused on the symbols your users actually need.

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.

Default Behavior

By default, classes with more than 5 methods are split: the class itself gets one page, and each method gets its own page in a companion “Methods” section. Classes with 5 or fewer methods keep their methods inline on the class page.

Configuring the Threshold

You can control this behavior with the inline_methods setting in great-docs.yml:

great-docs.yml

# Keep the default (split above 5 methods)
inline_methods: 5

# Custom threshold: split above 10 methods
inline_methods: 10

# Always inline: never split methods to separate pages
inline_methods: true

# Always split: every class gets separate method pages
inline_methods: false

Value	Behavior
`true`	Methods always stay inline on the class page, regardless of count
`false`	Methods always get their own pages (even for classes with 1–2 methods)
Integer `N`	Methods stay inline for classes with ≤N methods; classes with >N get split (default: `5`)

The examples below show what Great Docs generates in _quarto.yml. This file is regenerated on every build, so don’t edit it by hand. Use inline_methods in great-docs.yml to control the behavior and let the build produce the right output.

Small Classes (≤ threshold)

When a class has fewer methods than the threshold, all of its methods appear directly on the class page. Readers see everything in one place without navigating between pages. In the generated _quarto.yml, the class is listed as a simple entry:

_quarto.yml

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

This keeps the sidebar compact and works well for classes where the full method list fits comfortably on a single page.

Large Classes (> threshold)

When a class exceeds the threshold, Great Docs automatically splits it in the generated _quarto.yml. The methods are pulled out into a dedicated “Methods” section with individual pages, and the class entry suppresses inline method documentation so readers aren’t overwhelmed:

_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

Each method gets its own sidebar entry and its own page, making it easier to link to specific methods and to find them through search.

When to Adjust

The right setting depends on how users interact with your API documentation:

set inline_methods: true if your classes have many methods but users typically need to see them all at once (e.g., configuration objects, builder patterns).
set inline_methods: false if every method deserves its own discoverable page (e.g., a large framework API where methods are searched individually).
set a higher number (e.g., 10 or 15) if your classes tend to have moderate method counts and the default of 5 splits too aggressively.

When in doubt, start with the default and adjust once you see how your rendered documentation feels to navigate.

API Organization

The auto-generated reference is organized into sections by object type. This works well out of the box, but as your package grows you may want to group exports by domain rather than by type. Great Docs gives you full control over the section structure through the reference config in great-docs.yml, from simple title changes to completely custom groupings.

Default Sections

Great Docs creates sections automatically based on what it discovers. Only non-empty sections appear, so if your package has no enumerations or protocols, those sections are simply omitted. Here is the full set of possible sections:

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 exceeding the `inline_methods` threshold

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

The default sections group exports by type, but your users probably think about your API in terms of what it does, not what kind of Python object each export is. A data validation library might group things into “Schema Definition”, “Validators”, and “Error Handling” rather than “Classes”, “Functions”, and “Exceptions”. Custom organization lets you tell a story with your API reference, guiding readers to the right part of the documentation based on what they are trying to accomplish.

You can explicitly control the 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.

One thing to watch out for: the names in contents must match your package’s actual public API exactly. A misspelled name, a name that was renamed or removed, or a name that appears in the exclude list will silently produce a missing or empty reference page. If a page doesn’t render as expected after a build, check that the name in your reference config matches what your package exports.

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.

Documenting Inherited Methods

By default, only methods defined directly on a class are documented. Inherited methods are excluded unless you opt in. This keeps reference pages focused and avoids duplicating parent class methods on every child page (especially important in deep class hierarchies where it would add significant clutter).

If your class hierarchy uses inheritance and you want child classes to show inherited methods, there are two approaches.

Explicit member list. List the methods you want documented (including inherited ones) in the members key:

great-docs.yml

reference:
  - title: API
    contents:
      - BaseProcessor
      - name: AdvancedProcessor
        members:
          - process        # own method
          - validate       # inherited from BaseProcessor
          - reset          # inherited from BaseProcessor

This gives you full control over which inherited methods appear and in what order.

Auto-include inherited methods. Use include_inherited: true to automatically document all inherited methods without listing them explicitly:

great-docs.yml

reference:
  - title: Shapes
    contents:
      - Shape
      - name: Circle
        include_inherited: true  # includes area(), perimeter(), describe() from Shape

With this flag, the child class page will show its own methods plus all public methods inherited from parent classes.

Tip

You can combine both approaches. Use include_inherited: true for convenience, or provide an explicit members list when you want to cherry-pick specific inherited methods or control ordering.

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

Source links let readers jump straight from the documentation to the implementation, which is especially valuable during code reviews and debugging.

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.

This cleanup happens automatically during every build, so you don’t need to strip Sphinx syntax from your docstrings. If your package also publishes Sphinx-based docs, the same docstrings work in both systems without modification.

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

Either way, the rendered output reflects the current state of your package. You never need to manually edit generated reference pages.

Next Steps

Great Docs handles the tedious parts of API documentation (discovery, classification, layout, linking) so you can focus on writing clear docstrings. Whether your package exports a handful of functions or hundreds of classes, the reference section stays organized and up to date.

Writing Docstrings covers docstring format, sections, executable examples, and %nodoc
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

How Discovery Works

Static Analysis Benefits

What Gets Documented

Exclusion Rules

Smart Method Handling

Default Behavior

Configuring the Threshold

Small Classes (≤ threshold)

Large Classes (> threshold)

When to Adjust

API Organization

Default Sections

Custom Organization with reference Config

Custom Title and Description

Controlling Method Documentation

Documenting Inherited Methods

Excluding Items with exclude

Source Code Links

How It Works

Configuration

Submodule Introspection

Cross-Referencing

Sphinx & RST Cleanup

Sphinx Cross-Reference Roles

RST Admonition & Version Directives

Visual Enhancements

Type Labels

Code Styling

Responsive Design

Sidebar Filter

Refreshing API Documentation

Next Steps

Custom Organization with `reference` Config

Excluding Items with `exclude`