numpy / numpy/numpydoc

Docstring section for class constructors

Open
#255 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
355
Forks
181
Avg merge
1d 9h
Merged PRs (30d)
3

Description

Simply using the autosummary extension from sphinx burys classmethods amongst all of the other methods in a class. To make them easier for users to find, I could separately reference classmethods in an explicit methods section of the class docstring, but while classmethods are methods, the "Methods" title does not capture their role in class construction, nor why I included them in the methods section when other methods were not. I want there to be a prominent place for class constructors so that it is obvious from the documentation that these special methods perform a specific task. I would like to see something like a "Classmethods" section, or more descriptively, "Constructors", which would imply function and be a valid name even if a constructor wasn't technically decorated with @classmethod. Since the entries under this header would be methods of a class, the formating/handling of the entries could be the same as the standard methods section for classes.

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.

Research direction

Start by tracing how the Sphinx autosummary extension handles class docstrings and groups methods. Compare the existing methods-section behavior with the requested Classmethods or Constructors section; done means constructors are prominently separated while retaining the standard method entry formatting.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.