---
title: "Customize API Organization"
description: "Rearrange your API reference into domain-specific sections instead of the default type-based layout."
tags: [API, Customization]
---

# Customize API Organization

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:

```{.yaml filename="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:

```{.yaml filename="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:

```{.yaml filename="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](../user-guide/api-documentation.html) page in the User Guide.
