1:orphan: 2 3========================= 4Documentation Conventions 5========================= 6 7This document describes the conventions used in pip's documentation. We 8expect it to evolve over time as additional conventions are identified 9and past conventions are rendered obsolete. 10 11.. note:: 12 13 Currently, these conventions are not enforced automatically, and 14 need to be verified manually during code review. We are interested 15 in linters that can help us enforce these conventions automatically. 16 17 18Files 19===== 20 21Naming 22------ 23 24Folder names should be a single word, all lowercase. 25 26File names must use the kebab-case style (all lowercase, hyphen for 27separating words) and have the extension ``.rst``. 28 29Encoding 30-------- 31 32All files in our documentation must use UTF-8 encoding. 33 34Line Length 35----------- 36 37Limit all lines to a maximum of 72 characters, where possible. This may 38be exceeded when it does not make sense to abide by it (eg. long links, 39code blocks). 40 41Headings 42======== 43 44Use the following symbols to create headings: 45 46#. ``=`` with overline 47#. ``=`` 48#. ``-`` 49#. ``^`` 50#. ``'`` 51#. ``*`` 52 53For visual separation from the rest of the content, all other headings 54must have one empty line before and after. Heading 2 (``=``) should have 55two empty lines before, for indicating the end of the section prior to 56it. 57 58:: 59 60 ========= 61 Heading 1 62 ========= 63 64 Lorem ipsum dolor sit amet consectetur adipisicing elit. 65 66 67 Heading 2 68 ========= 69 70 Lorem ipsum dolor sit amet consectetur adipisicing elit. 71 72 Heading 3 73 --------- 74 75 Lorem ipsum dolor sit amet consectetur adipisicing elit. 76 77 Heading 4 78 ^^^^^^^^^ 79 80 Lorem ipsum dolor sit amet consectetur adipisicing elit. 81 82 Heading 5 83 ''''''''' 84 85 Lorem ipsum dolor sit amet consectetur adipisicing elit. 86 87 Heading 6 88 ********* 89 90 Lorem ipsum dolor sit amet consectetur adipisicing elit. 91 92 93Writing 94======= 95 96.. note:: 97 98 We're still discussing *how* pip should be capitalized in prose. The 99 current statement here is tentative. 100 101pip is a proper noun, and spelt all lowercase. Do not capitalize pip as 102"Pip" at the start of a sentence. 103 104Avoid using phrases such as "easy", "just", "simply" etc, which imply 105that the task is trivial. If it were trivial, the user wouldn't be 106reading the documentation for it. 107