McSinyx
/
pip
mirror of https://github.com/pypa/pip
1
1
Fork 0
Code Issues Releases Activity

Merge pull request #7948 from pradyunsg/docs/conventions-update-1 

Update docs conventions based on recent experience
This commit is contained in:
Pradyun Gedam 2020-04-13 04:54:18 +05:30 committed by GitHub
parent 745e21ff6e 113884b3a2
commit 7dde527ac9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 27 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
docs/html/development/conventions.rst
View File

@ -10,9 +10,9 @@ and past conventions are rendered obsolete.
.. note::
Currently, these conventions are not enforced automatically, and
need to be verified manually during code review. We are interested
in linters that can help us enforce these conventions automatically.
Currently, these conventions are not enforced automatically, and
need to be verified manually during code review. We are interested
in linters that can help us enforce these conventions automatically.
Files
@ -31,10 +31,6 @@ Encoding
All files in our documentation must use UTF-8 encoding.
File Layout
===========
Line Length
-----------
@ -42,31 +38,6 @@ Limit all lines to a maximum of 72 characters, where possible. This may
be exceeded when it does not make sense to abide by it (eg. long links,
code blocks).
Indentation
-----------
We use 4 spaces for indentation.
::
.. note::
Directive blocks
::
Code block.
Bullet lists are the only exception to the 4 spaces rule, using 2 spaces
when wrapping lines.
::
- This is a bullet list.
- This is a lot of text in a single bullet which would require wrapping
across multiple lines to fit in the line length limits.
Headings
========
@ -86,42 +57,47 @@ it.
::
=========
Heading 1
=========
=========
Heading 1
=========
Lorem ipsum dolor sit amet consectetur adipisicing elit.
Lorem ipsum dolor sit amet consectetur adipisicing elit.
Heading 2
=========
Heading 2
=========
Lorem ipsum dolor sit amet consectetur adipisicing elit.
Lorem ipsum dolor sit amet consectetur adipisicing elit.
Heading 3
---------
Heading 3
---------
Lorem ipsum dolor sit amet consectetur adipisicing elit.
Lorem ipsum dolor sit amet consectetur adipisicing elit.
Heading 4
^^^^^^^^^
Heading 4
^^^^^^^^^
Lorem ipsum dolor sit amet consectetur adipisicing elit.
Lorem ipsum dolor sit amet consectetur adipisicing elit.
Heading 5
'''''''''
Heading 5
'''''''''
Lorem ipsum dolor sit amet consectetur adipisicing elit.
Lorem ipsum dolor sit amet consectetur adipisicing elit.
Heading 6
*********
Heading 6
*********
Lorem ipsum dolor sit amet consectetur adipisicing elit.
Lorem ipsum dolor sit amet consectetur adipisicing elit.
Writing
=======
.. note::
We're still discussing *how* pip should be capitalized in prose. The
current statement here is tentative.
pip is a proper noun, and spelt all lowercase. Do not capitalize pip as
"Pip" at the start of a sentence.