openedx / openedx/openedx-authz

Documentation Search Index: use no-index to avoid duplication issue

Open
#145 0 comments 0 reactions 1 assignee View on GitHub

@MaferMazu is already working on this.

Since Jun 3, 2026.

documentation
Dominant language
Python
Stars
0
Forks
9
Avg merge
13d 9h
Merged PRs (30d)
9

Description

Description

API classes from openedx_authz.api modules are not included in the Sphinx search index, making them undiscoverable via the documentation search functionality. This to avoid warnings breaking the docs build.

The openedx_authz.api package re-exports all members from its submodules via from openedx_authz.api.data import * (and similar for other submodules). This causes Sphinx to find the same classes in multiple locations, generating duplicate object description warnings:

/home/mgmdy/Work/Envs/Local/nightly/openedx-authz/openedx_authz/api/data.py:docstring of openedx_authz.api.data.ActionData.NAMESPACE:1: WARNING: duplicate object description of openedx_authz.api.data.ActionData.NAMESPACE, other instance in openedx_authz.api, use :no-index: for one of them

The current workaround uses :no-index: on all automodule directives (via SPHINX_APIDOC_OPTIONS in docs/conf.py). While this eliminates the warnings, it also prevents classes from being added to the search index.

Impact

  • ✓ Documentation builds without warnings
  • ✓ Classes are documented and visible in HTML pages
  • ✗ Classes cannot be found using documentation search

Recommended Solution

Selectively apply :no-index: only to submodule sections, not to the main openedx_authz.api module, to allow classes to be indexed while avoiding duplicate warnings.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.