Consolidate guidance on prompts in interactive code examples
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 50/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Stale
- Tech stack
- python
- Domain
- documentation
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.
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.
- Dominant language
- Python
- Stars
- 2.1k
- Forks
- 1k
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 12
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.
More from python/devguide
-
type-feature
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
type-feature
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
topic-building python type-feature
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
-
needs: decision topic-test type-bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
topic-dev process type-feature
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
Similar issues
-
sponsored
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
Diaoul/subliminal#1382 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 92/100
-
triage/confirmed
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
agentscope-ai/agentscope#2775 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100