Consolidate guidance on prompts in interactive code examples
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 2.1k
- Forks
- 1k
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 12
Description
In the Documentation chapter, Style Guide / Code Examples has
The ellipsis for the sys.ps2 secondary interpreter prompt should only be used sparingly, where it is necessary to clearly differentiate between input lines and output lines. Besides contributing visual clutter, it makes it difficult for readers to cut-and-paste examples so they can experiment with variations.
(Perhaps it should be mentioned here that doctesting the code example requires such differentiation and hence requires secondary prompts. Perhaps the primary prompt should also be left off.)
reStructured Text Markup / Additional Markup Constructs / Showing Code Examples has
Representing an interactive session requires including the prompts and output along with the Python code. No special markup is required for interactive sessions. After the last line of input or output presented, there should not be an “unused” primary prompt; this is an example of what not to do:
>>>1 + 1
2
>>>
I think both advices should be in the same place and a reference added in the other.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Open the linked Style Guide / Code Examples and reStructured Text Markup / Showing Code Examples sections first. Consolidate their guidance on interactive prompts in one place, add a reference in the other, and ensure the resulting advice covers secondary prompts, doctesting, and the unused primary prompt example.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 50/100