python / python/devguide

Consolidate guidance on prompts in interactive code examples

Aberta
#1,135 3 comentários 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

help wanted topic-documentation type-bug type-feature
Linguagem predominante
Python
Estrelas
2.1k
Forks
1k
Merge médio
2d 12h
PRs com merge (30d)
12

Descrição

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.

Guia de contribuição

Abrir o guia de contribuição

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Direção de pesquisa

Abra primeiro as seções vinculadas „Style Guide / Code Examples“ e „reStructured Text Markup / Showing Code Examples“. Consolide as orientações sobre prompts interativos em um só lugar, adicione uma referência no outro e garanta que as orientações resultantes cubram prompts secundários, doctesting e o exemplo de prompt primário não utilizado.

Escrita pelo modelo de indexação a partir do texto da issue.

Avaliação

Stack de tecnologia
python
Domínio
documentation
Tipo de issue
Documentação
Dificuldade
2/5
Tempo estimado
1-3 horas
Status de atividade
Estagnada
Clareza
Claramente especificada
Facilidade para iniciantes
50/100

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.