astropy / astropy/sphinx-automodapi

Add an option to emit warnings if public objects don't have a docstring

Open
#45 3 comments 0 reactions 0 assignees View on GitHub
enhancement help wanted
Dominant language
Python
Stars
67
Forks
48
Avg merge
11h 52m
Merged PRs (30d)
1

Description

As originally mentioned in https://github.com/astropy/astropy-helpers/issues/195, it might be useful to have a way to be strict about requiring public functions, methods, and classes to have docstrings, so that we don't end up with empty docstrings in the API docs generated by sphinx-automodapi.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the linked astropy-helpers issue and tracing how sphinx-automodapi identifies public functions, methods, and classes before generating API documentation. Define done as an opt-in setting that reports public objects without docstrings and prevents silent empty entries in the generated Sphinx documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.