# SPDX-FileCopyrightText: Chris Wilson <christopher.david.wilson@gmail.com>
#
# SPDX-License-Identifier: Apache-2.0 OR MIT

nav:
  - index.md
  # When the navigation.sections feature is enabled in the material theme,
  # top-level sections are rendered as groups in the sidebar for viewports
  # above 1220px. When the navigation.indexes and navigation.tabs features
  # are also enabled, the top-level Python package's index.md page can end
  # up being directly attached to the package's section if a single-level
  # nav like the following is used:
  #
  # nav:
  #   - API Documentation: api/
  #
  # As a result, any pages generated for the child modules and subpackages
  # immediately under the top-level package will not be indented relative to
  # the package. At a quick glance, this can be confusing.
  #
  # For example, given a Python package like the following:
  #
  #   package/
  #     __init__.py
  #     module.py
  #     subpackage/
  #       module2.py
  #
  # If the API docs are located at the /api/ path, the following nav would
  # be generated:
  #
  # API Documentation (Top-level section for tab)
  #   [mod] package (Section linked to <API_DOC_DIR>/index.md)
  #   [mod] module (Page linked to <API_DOC_DIR>/module.md)
  #   [mod] subpackage (Page linked to <API_DOC_DIR>/subpackage/index.md)
  #     [mod] module2 (Page linked to <API_DOC_DIR>/subpackage/module2.md)
  #
  # It's not obvious that "module" and "subpackage" are nested under the
  # "package" (i.e package.module & package.subpackage).
  #
  # By nesting the generated API docs under an additional section (e.g.
  # "Reference"), the Python package name is not associated with the top two
  # levels in the nav, and the modules/subpackages are correctly indented under
  # the top-level package:
  #
  # Reference (Top-level section for tab)
  #   API Documentation (section)
  #   [mod] package (Section linked to <API_DOC_DIR>/index.md)
  #     [mod] module (Page linked to <API_DOC_DIR>/module.md)
  #     [mod] subpackage (Page linked to <API_DOC_DIR>/subpackage/index.md)
  #       [mod] module2 (Page linked to <API_DOC_DIR>/subpackage/module2.md)
  - API Documentation: api
