Customize API Organization

Rearrange your API reference into domain-specific sections instead of the default type-based layout.

By default, Great Docs organizes your API reference by type: all classes together, all functions together, and so on. For larger packages, it often makes more sense to group items by domain or feature area. The reference config in great-docs.yml gives you full control over this.

Define Custom Sections

Replace the auto-generated structure with explicit sections that reflect your package’s domain model. Each section has a title, an optional description, and a list of items:

great-docs.yml

reference:
  sections:
    - title: Data Loading
      desc: Read and parse data from various sources
      contents:
        - read_csv
        - read_json
        - read_parquet
        - DataSource

    - title: Transformations
      desc: Transform and reshape data
      contents:
        - pivot
        - melt
        - merge
        - Filter

    - title: Output
      desc: Export results to files or databases
      contents:
        - write_csv
        - write_json
        - to_database

Items appear in the sidebar in the order listed. You only need to list items you want documented; anything not listed is omitted.

Separate Methods from Classes

For classes with many methods, you can suppress inline method documentation and list methods in their own section. Set members: false on the class entry, then reference each method individually:

great-docs.yml

reference:
  sections:
    - title: Core
      desc: Primary classes
      contents:
        - name: Pipeline
          members: false

    - title: Pipeline Methods
      desc: Methods for building and executing pipelines
      contents:
        - Pipeline.add_step
        - Pipeline.run
        - Pipeline.validate
        - Pipeline.reset

This keeps the class page focused on the overview while giving each method its own dedicated page.

Add a Custom Heading and Description

You can set a page-level title and description that appear above your sections on the reference index page:

great-docs.yml

reference:
  title: "API Reference"
  desc: >-
    Complete reference for all public classes and functions.
    Organized by feature area.
  sections:
    - title: Core
      contents:
        - MyClass

Without title and desc, the page heading defaults to “Reference” with no introductory text.

Tips

When you provide an explicit reference config, Great Docs uses it as-is and does not auto-generate sections. If you add new exports to your package, remember to add them to the config as well, or they will not appear in the documentation.

To see what your package currently exports, run great-docs scan. This lists all discovered symbols along with their types, which can help you decide how to group them.

For the full details on API organization, see the API Documentation page in the User Guide.