Markup github-flavored-markdown readme. Improve this question. Follow edited Dec 30 '20 at 8:04. 7,200 5 5 gold badges 38 38 silver badges 64 64. Jul 15, 2016 README files are a quick and simple way for other users to learn more about your work. Wikis on GitHub help you present in-depth information about your project in a useful way. It’s a good idea to at least have a README on your project, because it’s the first thing many people will read when they first find your work. Sep 16, 2020 README.md React Rich Text Editor This is a UI component built completely in React that is meant to be a full-featured textarea replacement similar to CKEditor, TinyMCE and other rich text 'WYSIWYG' editors.

PEP:	287
Title:	reStructuredText Docstring Format
Author:	David Goodger <goodger at python.org>
Discussions-To:	<doc-sig at python.org>
Status:	Active
Type:	Informational
Created:	25-Mar-2002
Post-History:	02-Apr-2002
Replaces:	216

Contents

When plaintext hasn't been expressive enough for inline documentation,Python programmers have sought out a format for docstrings. This PEPproposes that the reStructuredText markup[5] be adopted as a standardmarkup format for structured plaintext documentation in Pythondocstrings, and for PEPs and ancillary documents as well.reStructuredText is a rich and extensible yet easy-to-read,what-you-see-is-what-you-get plaintext markup syntax.

Only the low-level syntax of docstrings is addressed here. This PEPis not concerned with docstring semantics or processing at all (seePEP 256 for a 'Road Map to the Docstring PEPs'). Nor is it an attemptto deprecate pure plaintext docstrings, which are always going to belegitimate. The reStructuredText markup is an alternative for thosewho want more expressive docstrings.

Programmers are by nature a lazy breed. We reuse code with functions,classes, modules, and subsystems. Through its docstring syntax,Python allows us to document our code from within. The 'holy grail'of the Python Documentation Special Interest Group (Doc-SIG[6]) has beena markup syntax and toolset to allow auto-documentation, where thedocstrings of Python systems can be extracted in context and processedinto useful, high-quality documentation for multiple purposes.

Document markup languages have three groups of customers: the authorswho write the documents, the software systems that process the data,and the readers, who are the final consumers and the most importantgroup. Most markups are designed for the authors and softwaresystems; readers are only meant to see the processed form, either onpaper or via browser software. ReStructuredText is different: it isintended to be easily readable in source form, without prior knowledgeof the markup. ReStructuredText is entirely readable in plaintextformat, and many of the markup forms match common usage (e.g.,*emphasis*), so it reads quite naturally. Yet it is rich enoughto produce complex documents, and extensible so that there are fewlimits. Of course, to write reStructuredText documents some priorknowledge is required.

The markup offers functionality and expressivity, while maintainingeasy readability in the source text. The processed form (HTML etc.)makes it all accessible to readers: inline live hyperlinks; live linksto and from footnotes; automatic tables of contents (with livelinks!); tables; images for diagrams etc.; pleasant, readable styledtext.

The reStructuredText parser is available now, part of the Docutils[24]project. Standalone reStructuredText documents and PEPs can beconverted to HTML; other output format writers are being worked on andwill become available over time. Work is progressing on a Pythonsource 'Reader' which will implement auto-documentation fromdocstrings. Authors of existing auto-documentation tools areencouraged to integrate the reStructuredText parser into theirprojects, or better yet, to join forces to produce a world-classtoolset for the Python standard library.

Tools will become available in the near future, which will allowprogrammers to generate HTML for online help, XML for multiplepurposes, and eventually PDF, DocBook, and LaTeX for printeddocumentation, essentially 'for free' from the existing docstrings.The adoption of a standard will, at the very least, benefit docstringprocessing tools by preventing further 'reinventing the wheel'.

Eventually PyDoc, the one existing standard auto-documentation tool,could have reStructuredText support added. In the interim it willhave no problem with reStructuredText markup, since it treats alldocstrings as preformatted plaintext.

These are the generally accepted goals for a docstring format, asdiscussed in the Doc-SIG:

1. It must be readable in source form by the casual observer.
2. It must be easy to type with any standard text editor.
3. It must not need to contain information which can be deduced fromparsing the module.
4. It must contain sufficient information (structure) so it can beconverted to any reasonable markup format.
5. It must be possible to write a module's entire documentation indocstrings, without feeling hampered by the markup language.

reStructuredText meets and exceeds all of these goals, and sets itsown goals as well, even more stringent. See Docstring-SignificantFeatures below.

The goals of this PEP are as follows:

1. To establish reStructuredText as a standard structured plaintextformat for docstrings (inline documentation of Python modules andpackages), PEPs, README-type files and other standalone documents.'Accepted' status will be sought through Python community consensusand eventual BDFL pronouncement.

   Please note that reStructuredText is being proposed as astandard, not the only standard. Its use will be entirelyoptional. Those who don't want to use it need not.

2. To solicit and address any related concerns raised by the Pythoncommunity.

3. To encourage community support. As long as multiple competingmarkups are out there, the development community remains fractured.Once a standard exists, people will start to use it, and momentumwill inevitably gather.

4. To consolidate efforts from related auto-documentation projects.It is hoped that interested developers will join forces and work ona joint/merged/common implementation.

Once reStructuredText is a Python standard, effort can be focused ontools instead of arguing for a standard. Python needs a standard setof documentation tools.

With regard to PEPs, one or both of the following strategies may beapplied:

1. Keep the existing PEP section structure constructs (one-linesection headers, indented body text). Subsections can either beforbidden, or supported with reStructuredText-style underlinedheaders in the indented body text.
2. Replace the PEP section structure constructs with thereStructuredText syntax. Section headers will require underlines,subsections will be supported out of the box, and body text neednot be indented (except for block quotes).

Strategy (b) is recommended, and its implementation is complete.

Support for RFC 2822 headers has been added to the reStructuredTextparser for PEPs (unambiguous given a specific context: the firstcontiguous block of the document). It may be desired to concretelyspecify what over/underline styles are allowed for PEP sectionheaders, for uniformity.

The lack of a standard syntax for docstrings has hampered thedevelopment of standard tools for extracting and converting docstringsinto documentation in standard formats (e.g., HTML, DocBook, TeX).There have been a number of proposed markup formats and variations,and many tools tied to these proposals, but without a standarddocstring format they have failed to gain a strong following and/orfloundered half-finished.

Throughout the existence of the Doc-SIG, consensus on a singlestandard docstring format has never been reached. A lightweight,implicit markup has been sought, for the following reasons (amongothers):

1. Docstrings written within Python code are available from within theinteractive interpreter, and can be 'print'ed. Thus the use ofplaintext for easy readability.
2. Programmers want to add structure to their docstrings, withoutsacrificing raw docstring readability. Unadorned plaintext cannotbe transformed ('up-translated') into useful structured formats.
3. Explicit markup (like XML or TeX) is widely considered unreadableby the uninitiated.
4. Implicit markup is aesthetically compatible with the clean andminimalist Python syntax.

Many alternative markups for docstrings have been proposed on theDoc-SIG over the years; a representative sample is listed below. Eachis briefly analyzed in terms of the goals stated above. Please notethat this is not intended to be an exclusive list of all existingmarkup systems; there are many other markups (Texinfo, Doxygen, TIM,YODL, AFT, ...) which are not mentioned.

• XML[7], SGML[8], DocBook[9], HTML[10], XHTML[11]

  XML and SGML are explicit, well-formed meta-languages suitable forall kinds of documentation. XML is a variant of SGML. They arebest used behind the scenes, because to untrained eyes they areverbose, difficult to type, and too cluttered to read comfortably assource. DocBook, HTML, and XHTML are all applications of SGMLand/or XML, and all share the same basic syntax and the sameshortcomings.

• TeX is similar to XML/SGML in that it's explicit, but not very easyto write, and not easy for the uninitiated to read.

• Most Perl modules are documented in a format called POD (Plain OldDocumentation). This is an easy-to-type, very low level format withstrong integration with the Perl parser. Many tools exist to turnPOD documentation into other formats: info, HTML and man pages,among others. However, the POD syntax takes after Perl itself interms of readability.

• Special comments before Java classes and functions serve to documentthe code. A program to extract these, and turn them into HTMLdocumentation is called javadoc, and is part of the standard Javadistribution. However, JavaDoc has a very intimate relationshipwith HTML, using HTML tags for most markup. Thus it shares thereadability problems of HTML.

• Setext[15], StructuredText[16]

  Early on, variants of Setext (Structure Enhanced Text), includingZope Corp's StructuredText, were proposed for Python docstringformatting. Hereafter these variants will collectively be called'STexts'. STexts have the advantage of being easy to read withoutspecial knowledge, and relatively easy to write.

  Although used by some (including in most existing Pythonauto-documentation tools), until now STexts have failed to becomestandard because:

  • STexts have been incomplete. Lacking 'essential' constructs thatpeople want to use in their docstrings, STexts are rendered lessthan ideal. Note that these 'essential' constructs are notuniversal; everyone has their own requirements.
  • STexts have been sometimes surprising. Bits of text areunexpectedly interpreted as being marked up, leading to userfrustration.
  • SText implementations have been buggy.
  • Most STexts have no formal specification except for theimplementation itself. A buggy implementation meant a buggy spec,and vice-versa.
  • There has been no mechanism to get around the SText markup ruleswhen a markup character is used in a non-markup context. In otherwords, no way to escape markup.

Proponents of implicit STexts have vigorously opposed proposals forexplicit markup (XML, HTML, TeX, POD, etc.), and the debates havecontinued off and on since 1996 or earlier.

reStructuredText is a complete revision and reinterpretation of theSText idea, addressing all of the problems listed above.

The specification and user documentaton for reStructuredText isquite extensive. Rather than repeating or summarizing it allhere, links to the originals are provided.

Please first take a look at A ReStructuredText Primer[17], a short andgentle introduction. The Quick reStructuredText[18] user referencequickly summarizes all of the markup constructs. For complete andextensive details, please refer to the following documents:

In addition, Problems With StructuredText[22] explains many markupdecisions made with regards to StructuredText, and A Record ofreStructuredText Syntax Alternatives[23] records markup decisions madeindependently.

• A markup escaping mechanism.

  Backslashes () are used to escape markup characters when neededfor non-markup purposes. However, the inline markup recognitionrules have been constructed in order to minimize the need forbackslash-escapes. For example, although asterisks are used foremphasis, in non-markup contexts such as '*' or '(*)' or 'x * y',the asterisks are not interpreted as markup and are left unchanged.For many non-markup uses of backslashes (e.g., describing regularexpressions), inline literals or literal blocks are applicable; seethe next item.

• Markup to include Python source code and Python interactivesessions: inline literals, literal blocks, and doctest blocks.

  Inline literals use double-backquotes to indicate program I/O orcode snippets. No markup interpretation (including backslash-escape[] interpretation) is done within inline literals.

  Literal blocks (block-level literal text, such as code excerpts orASCII graphics) are indented, and indicated with a double-colon('::') at the end of the preceding paragraph (right here -->):

  Doctest blocks begin with '>>> ' and end with a blank line. Neitherindentation nor literal block double-colons are required. Forexample:

• Markup that isolates a Python identifier: interpreted text.

  Text enclosed in single backquotes is recognized as 'interpretedtext', whose interpretation is application-dependent. In thecontext of a Python docstring, the default interpretation ofinterpreted text is as Python identifiers. The text will be markedup with a hyperlink connected to the documentation for theidentifier given. Lookup rules are the same as in Python itself:LGB namespace lookups (local, global, builtin). The 'role' of theinterpreted text (identifying a class, module, function, etc.) isdetermined implicitly from the namespace lookup. For example:

  Each piece of interpreted text is looked up according to the localnamespace of the block containing its docstring.

• Markup that isolates a Python identifier and specifies its type:interpreted text with roles.

  Although the Python source context reader is designed not to requireexplicit roles, they may be used. To classify identifiersexplicitly, the role is given along with the identifier in eitherprefix or suffix form:

  The syntax chosen for roles is verbose, but necessarily so (ifanyone has a better alternative, please post it to the Doc-SIG[6]).The intention of the markup is that there should be little need touse explicit roles; their use is to be kept to an absolute minimum.

• Markup for 'tagged lists' or 'label lists': field lists.

  Field lists represent a mapping from field name to field body.These are mostly used for extension syntax, such as 'bibliographicfield lists' (representing document metadata such as author, date,and version) and extension attributes for directives (see below).They may be used to implement methodologies (docstring semantics),such as identifying parameters, exceptions raised, etc.; such usageis beyond the scope of this PEP.

  A modified RFC 2822 syntax is used, with a colon before as well asafter the field name. Field bodies are more versatile as well;they may contain multiple field bodies (even nested field lists).For example:

  Standard RFC 2822 header syntax cannot be used for this constructbecause it is ambiguous. A word followed by a colon at thebeginning of a line is common in written text.

• Markup extensibility: directives and substitutions.

  Directives are used as an extension mechanism for reStructuredText,a way of adding support for new block-level constructs withoutadding new syntax. Directives for images, admonitions (note,caution, etc.), and tables of contents generation (among others)have been implemented. For example, here's how to place an image:

  Substitution definitions allow the power and flexibility ofblock-level directives to be shared by inline text. For example:

• Section structure markup.

  Section headers in reStructuredText use adornment via underlines(and possibly overlines) rather than indentation. For example:

1. Is reStructuredText rich enough?

   Yes, it is for most people. If it lacks some construct that isrequired for a specific application, it can be added via thedirective mechanism. If a useful and common construct has beenoverlooked and a suitably readable syntax can be found, it can beadded to the specification and parser.

2. Is reStructuredText too rich?

   For specific applications or individuals, perhaps. In general, no.

   Since the very beginning, whenever a docstring markup syntax hasbeen proposed on the Doc-SIG[6], someone has complained about thelack of support for some construct or other. The reply was oftensomething like, 'These are docstrings we're talking about, anddocstrings shouldn't have complex markup.' The problem is that aconstruct that seems superfluous to one person may be absolutelyessential to another.

   reStructuredText takes the opposite approach: it provides a richset of implicit markup constructs (plus a generic extensionmechanism for explicit markup), allowing for all kinds ofdocuments. If the set of constructs is too rich for a particularapplication, the unused constructs can either be removed from theparser (via application-specific overrides) or simply omitted byconvention.

3. Why not use indentation for section structure, like StructuredTextdoes? Isn't it more 'Pythonic'?

   Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG post:

   I still think that using indentation to indicate sectioning iswrong. If you look at how real books and other printpublications are laid out, you'll notice that indentation isused frequently, but mostly at the intra-section level.Indentation can be used to offset lists, tables, quotations,examples, and the like. (The argument that docstrings aredifferent because they are input for a text formatter is wrong:the whole point is that they are also readable withoutprocessing.)

   I reject the argument that using indentation is Pythonic: textis not code, and different traditions and conventions hold.People have been presenting text for readability for over 30centuries. Let's not innovate needlessly.

   See Section Structure via Indentation[25] in Problems WithStructuredText[22] for further elaboration.

4. Why use reStructuredText for PEPs? What's wrong with the existingstandard?

   The existing standard for PEPs is very limited in terms of generalexpressibility, and referencing is especially lacking for such areference-rich document type. PEPs are currently converted intoHTML, but the results (mostly monospaced text) are less thanattractive, and most of the value-added potential of HTML(especially inline hyperlinks) is untapped.

   Making reStructuredText a standard markup for PEPs will enable muchricher expression, including support for section structure, inlinemarkup, graphics, and tables. In several PEPs there are ASCIIgraphics diagrams, which are all that plaintext documents cansupport. Since PEPs are made available in HTML form, the abilityto include proper diagrams would be immediately useful.

   Current PEP practices allow for reference markers in the form '[1]'in the text, and the footnotes/references themselves are listed ina section toward the end of the document. There is currently nohyperlinking between the reference marker and thefootnote/reference itself (it would be possible to add this topep2html.py, but the 'markup' as it stands is ambiguous andmistakes would be inevitable). A PEP with many references (such asthis one ;-) requires a lot of flipping back and forth. Whenrevising a PEP, often new references are added or unused referencesdeleted. It is painful to renumber the references, since it has tobe done in two places and can have a cascading effect (insert asingle new reference 1, and every other reference has to berenumbered; always adding new references to the end is suboptimal).It is easy for references to go out of sync.

   PEPs use references for two purposes: simple URL references andfootnotes. reStructuredText differentiates between the two. A PEPmight contain references like this:

   Reference 1 is a simple URL reference. Reference 2 is a footnotecontaining text and a URL. Reference 3 is a footnote containingtext only. Rewritten using reStructuredText, this PEP could looklike this:

   URLs and footnotes can be defined close to their references ifdesired, making them easier to read in the source text, and makingthe PEPs easier to revise. The 'References and Footnotes' sectioncan be auto-generated with a document tree transform. Footnotesfrom throughout the PEP would be gathered and displayed under astandard header. If URL references should likewise be written outexplicitly (in citation form), another tree transform could beused.

   URL references can be named ('frungible doodads'), and can bereferenced from multiple places in the document without additionaldefinitions. When converted to HTML, references will be replacedwith inline hyperlinks (HTML <a> tags). The two footnotes areautomatically numbered, so they will always stay in sync. Thefirst footnote also contains an internal reference name, 'pep9876',so it's easier to see the connection between reference and footnotein the source text. Named footnotes can be referenced multipletimes, maintaining consistent numbering.

   The '#pep9876' footnote could also be written in the form of acitation:

   Footnotes are numbered, whereas citations use text for theirreferences.

5. Wouldn't it be better to keep the docstring and PEP proposalsseparate?

   The PEP markup proposal may be removed if it is deemed that thereis no need for PEP markup, or it could be made into a separate PEP.If accepted, PEP 1, PEP Purpose and Guidelines [1], and PEP9, Sample PEP Template [2] will be updated.

   It seems natural to adopt a single consistent markup standard forall uses of structured plaintext in Python, and to propose it allin one place.

6. The existing pep2html.py script converts the existing PEP format toHTML. How will the new-format PEPs be converted to HTML?

   A new version of pep2html.py with integrated reStructuredTextparsing has been completed. The Docutils project supports PEPswith a 'PEP Reader' component, including all functionalitycurrently in pep2html.py (auto-recognition of PEP & RFC references,email masking, etc.).

7. Who's going to convert the existing PEPs to reStructuredText?

   PEP authors or volunteers may convert existing PEPs if they like,but there is no requirement to do so. The reStructuredText-basedPEPs will coexist with the old PEP standard. The pep2html.pymentioned in answer 6 processes both old and new standards.

8. Why use reStructuredText for README and other ancillary files?

   The reasoning given for PEPs in answer 4 above also applies toREADME and other ancillary files. By adopting a standard markup,these files can be converted to attractive cross-referenced HTMLand put up on python.org. Developers of other projects can alsotake advantage of this facility for their own documentation.

9. Won't the superficial similarity to existing markup conventionscause problems, and result in people writing invalid markup (andnot noticing, because the plaintext looks natural)? How forgivingis reStructuredText of 'not quite right' markup?

   There will be some mis-steps, as there would be when moving fromone programming language to another. As with any language,proficiency grows with experience. Luckily, reStructuredText is avery little language indeed.

   As with any syntax, there is the possibility of syntax errors. Itis expected that a user will run the processing system over theirinput and check the output for correctness.

   In a strict sense, the reStructuredText parser is very unforgiving(as it should be; 'In the face of ambiguity, refuse the temptationto guess' [3] applies to parsing markup as well as computerlanguages). Here's design goal 3 from An Introduction toreStructuredText[19]:

   Unambiguous. The rules for markup must not be open forinterpretation. For any given input, there should be one andonly one possible output (including error output).

   While unforgiving, at the same time the parser does try to behelpful by producing useful diagnostic output ('system messages').The parser reports problems, indicating their level of severity(from least to most: debug, info, warning, error, severe). Theuser or the client software can decide on reporting thresholds;they can ignore low-level problems or cause high-level problems tobring processing to an immediate halt. Problems are reportedduring the parse as well as included in the output, often withtwo-way links between the source of the problem and the systemmessage explaining it.

10. Will the docstrings in the Python standard library modules beconverted to reStructuredText?

    No. Python's library reference documentation is maintainedseparately from the source. Docstrings in the Python standardlibrary should not try to duplicate the library referencedocumentation. The current policy for docstrings in the Pythonstandard library is that they should be no more than concisehints, simple and markup-free (although many do contain ad-hocimplicit markup).

11. I want to write all my strings in Unicode. Will anythingbreak?

    The parser fully supports Unicode. Docutils supports arbitraryinput and output encodings.

12. Why does the community need a new structured text design?

    The existing structured text designs are deficient, for thereasons given in 'Rationale' above. reStructuredText aims to be acomplete markup syntax, within the limitations of the 'readableplaintext' medium.

13. What is wrong with existing documentation methodologies?

    What existing methodologies? For Python docstrings, there isno official standard markup format, let alone a documentationmethodology akin to JavaDoc. The question of methodology is at amuch higher level than syntax (which this PEP addresses). It ispotentially much more controversial and difficult to resolve, andis intentionally left out of this discussion.

[1]	PEP 1, PEP Guidelines, Warsaw, Hylton(http://www.python.org/dev/peps/pep-0001/)

[2]	PEP 9, Sample PEP Template, Warsaw(http://www.python.org/dev/peps/pep-0009/)

[3]	From The Zen of Python (by Tim Peters)[26] (or just'import this' in Python)

[4]	PEP 216, Docstring Format, Zadka(http://www.python.org/dev/peps/pep-0216/)

[5]	http://docutils.sourceforge.net/rst.html

[6]	(1, 2, 3, 4)http://www.python.org/sigs/doc-sig/

[7]	http://www.w3.org/XML/

[8]	http://www.oasis-open.org/cover/general.html

[9]	http://docbook.org/tdg/en/html/docbook.html

[10]	http://www.w3.org/MarkUp/

[11]	http://www.w3.org/MarkUp/#xhtml1

[12]	http://www.tug.org/interest.html

[13]	http://perldoc.perl.org/perlpod.html

[14]	http://java.sun.com/j2se/javadoc/

[15]	http://docutils.sourceforge.net/mirror/setext.html

[16]	http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage

[17]	http://docutils.sourceforge.net/docs/user/rst/quickstart.html

[18]	http://docutils.sourceforge.net/docs/user/rst/quickref.html

[19]	(1, 2)http://docutils.sourceforge.net/docs/ref/rst/introduction.html

[20]	http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

[21]	http://docutils.sourceforge.net/docs/ref/rst/directives.html

[22]	(1, 2)http://docutils.sourceforge.net/docs/dev/rst/problems.html

[23]	http://docutils.sourceforge.net/docs/dev/rst/alternatives.html

[24]	http://docutils.sourceforge.net/

[25]	http://docutils.sourceforge.net/docs/dev/rst/problems.html#section-structure-via-indentation

[26]	http://www.python.org/doc/Humor.html#zen

This document has been placed in the public domain.

Readme Markup Bold

Some text is borrowed from PEP 216, Docstring Format [4], byMoshe Zadka.

Special thanks to all members past & present of the Python Doc-SIG[6].

Readme Markup Language

Source: https://github.com/python/peps/blob/master/pep-0287.txt