PyCQA / PyCQA/docformatter

Method to ignore portions of docstring [Community Feedback]

Open
#144 14 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C: stakeholder community feedback P: enhancement S: feedback U: low
Dominant language
Python
Stars
598
Forks
93
PR merge metrics
No merged PRs in 30d

Description

It would be useful to have a feature to tell docformatter to leave part of the docstring alone. For example, someone may have manually set up part of the docstring exactly as they want it and don't want it to be touched.

This issue follows from and continues the discussion here.

The proposal in that comment suggests adding # docfmt: off and # docfmt: on to the docstring. Assuming the same part of every docstring needs to be ignored, the problem is that it requires changing every docstring to add those comment directives which is not practical for a large project and there is the possibility that the directives will confuse other tools that parse the docstring. I think there needs to be a way to globally set whether docformatter ignores part of each docstring without needing to modify every docstring in a project.

Contributor guide

No contributing guide indexed for this repository

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 reviewing the discussion linked from issue 127 and the existing docformatter configuration and entry points. Clarify how a project-wide setting should identify the protected portion of each docstring without modifying every docstring. Done means the agreed behavior is documented and verified for both ignored and normally formatted portions.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.