How to Markdown and Document

Document Your Work

Leonardo Da Vinci used journals to sketch, develop and eventually pass on his ideas. Alexander von Humboldt documented many of his journeys in travel journals and Marie Skłodowska Curie wrote down the theory of “radioactivity” using pens and papers. Today, writing media have evolved into infinite digital oceans with sophisticated tools for documenting code and ideas. Also, how we look for and retrieve information has evolved from searching for lexicon entries to using keywords in search engines. So if you have made an ingenious discovery, you want to make sure you document it well so that others can understand and use it. You also want to make sure that others can find your stroke of genius in digital media. You also want to make sure that others can find your stroke of genius in digital media. One of the most widespread methods for documenting and spreading ideas is the use of so-called wikis (from Hawaiian: fast), which can easily be written in markdown language. GitHub provides comprehensive, easy-to-read explanations for project documentation with Markdown as core element. This page presents the basics of the markdown language to leverage wikis. Moreover, the powerful alternative of using reStructuredText in Sphinx-based documentations is introduced.

Tip

Write the Docs provides comprehensive guides for code documentation. Take about 10 minutes to read how to save days of work.

What to Document?

Good code documentation starts with a qualitative and concise description of software (e.g., a Python package) capacities, products, and requirements. It also provides workflows for installing and using the software, at best with illustrative examples. Finally, a good troubleshooting section enables users to find problems in their data setup or software usage. To enable future development and maintenance, a Contributing section provides * good-practice guidelines* for coding new software capacities.

Present Your Software or Project

This section intends to advertise the benefits and capacities of the software: Tell users briefly the purpose of the software, why it is unique and what it produces.

Requirements

A section on requirements should tell users or stakeholders:

• What system requirements are needed?

• Which dependencies does the software or project have (e.g., other Python packages such as NumPy)?

• What input data are needed to run the software?

Installation

An installation section should describe step-by-step the installation of the software (e.g., how to download and access your Python package) or the workflow of a project. Screenshots can be helpful. The Requirements section should already have clarified what users need for the installation.

Usage

A section on usage should describe how the software can be used, starting with basics such as importing the software as Python package. In addition, it should mention possible treatments of input and output data (i.e., pre- and post-processing, respectively). If available, add more complex functionalities consecutively in a logical order.

To truly make your software useful to others, add a case study. Most users will not read the detailed code documentation until they get the software to run once and see what it can do. A use case also helps to check the logic of your code and gives users the opportunity to bridge imperfect code documentation sections to their workflow. This can sometimes be necessary, even if your code is certainly perfect and the documentation is foolproof.

Troubleshooting

Sure, your code and workflow are error-free and of course, only the user makes mistakes. Anyway, show compassion and integrate specific Exception Handling with try - except statements in the source code, which point out possible error sources. These error (and maybe even warning) messages should all be listed in a Troubleshoot section of the code documentation. Any source of error (message) should be documented regarding the following aspects:

• Cause: Possible reasons for why an error occurs.

• Remedy: Steps for troubleshooting an error.

Contributing

Your software is brilliant. To make the software even more brilliant, foolproof, and powerful, it is a great idea (actually: an absolute must) to get more authors on the development team. However, any other author likely has individual preferences when it comes to code standards. So make sure to set up clear rules for other contributors from the beginning. For example, define clear code conventions as explained in the Code Style and Conventions section.

Markdown

For writing a documentation of a code or project in web-publish-ready format, cross-platform typesetting is needed. For this purpose, Markdown represents a good choice (among others, such as reStructuredText). Markdown was created in 2004 and is a simple markup language that is intuitive and easy to learn. Markup languages structure the content of plain text documents regarding the way a document is displayed to end-users (Rich Text Format). Other popular markup languages are for example TeX and XML (Extensible Markup Language). Markdown became a popular tool for writing syntactically distinguishable computer text that is then translated into Rich Text Format flavor. Here is an example of how Markdown works:

Raw Markdown

# Better than Word-like rich text editors
*OS*-independent functionality:
- Avoid formatting of the same kind of thing redundantly (and inconsistently)
- Backwards compatibility
- Formulae handling
- ... and many more ...

Rendered

Better than Word-like rich text editors

OS-independent functionality:

• Avoid formatting of the same kind of thing redundantly (and inconsistently)

• Backwards compatibility

• Formulae handling

• … and many more …

Markdown Editors (IDEs)

Many text editors provide Markdown add-ons and Markdown-only editors are losing their significance more and more. Editors that simultaneously support Markdown and programming languages like Python or R are state of the art and therefore recommended.

Basic text editors that support Markdown are listed here. Popular and multi-platform IDEs for editing Markdown (.md) files are JupyterLab or PyCharm.

Markdown Command Overview and Image Implementation

The following table and sections provide an overview of basic markdown commands. There are much more options out there, which you can find by using your favorite search engine with the keywords markdown guide.

Feature	Code	Example
Blockquote	`	A quote`
Bold text	**Bold**	Bold
Code block (inline)	inline `code`	inline `code`
Heading 1	# Heading 1	Heading 1
Heading 2	## Heading 2	Heading 2
Heading 3	### Heading 3	Heading 3
Horizontal rule	*** or ===	——-
Hyperlink	[Link](https://fruitsinfo.com)	Link
Hyperlink to section	[Link](https://fruitsinfo.com)#apples	Link to apple-section
Image	
Italic text	*italic*	italic
Numbered list item	1. numbered item	1. Numbered item
Reference (defined)	[Defined Reference][wiki]	Defined Reference
Reference (definition)	[wiki]: https://wikipedia.org	Place at file bottom
Strikethrough	~~Strikethrough~~	~~Strikethrough~~

Itemization (Un-numbered Lists)

Itemized list section can be produced using *, +, or - symbols with tabs that determine the list indentation:

Raw Markdown

* level 1 item
    - level 2 item
    - another level 2 item
        + level 3 item
* next level 1 item

Rendered

• level 1 item

  • level 2 item

  • another level 2 item

    • level 3 item

• next level 1 item

Tables

Table columns are separated by a | sign. The first row determines row headers and the second row the alignment through the use of : (see below example).

Raw Markdown

| Fruit | Kingdom | Genus |
|-------|:-------:|------:|
|Banana | Plantae | Musa  |
|Jackfruit|Plantae|Artocarpus|

Rendered

Fruit	Kingdom	Genus
Banana	Plantae	Musa
Jackfruit	Plantae	Artocarpus

Converting complex tables from workbooks (e.g., from LibreOffice Calc or MS Excel) is possible with many online tools, and here is just one example from Dave Johnson: https://thisDaveJ.com.

Math Expressions: Equations

Math expressions and equations must be implemented as text in standard Markdown. GitHubs markdown interpreter does not support many external TeX-like equation renderers for reasons of security. However, GitHub users can still render TeX-like equations with the following code:

<img src="https://render.githubusercontent.com/render/math?math=sin{\alpha} = \sqrt{1-cos^{2}\alpha}">

This results in

Note that the equation starts after math&math=. Thus for using the math snippet in a document, copy and modify the following expression <img src="https://render.githubusercontent.com/render/math?math=TYPE =  EQUATION HERE">.

Html - Markdown

html structures can be flawlessly used in Markdown, which itself is nothing else than simplified html. Therefore, any html structure can be used within markdown and the above-shown equation implementation already represents the first example for html usage in a Markdown document. The following sections provide an overview of some more or less frequently used html symbols that also work with Markdown.

Greek Letters

To use greek letters in inline text, use html language, where &lettername; produces the desired Greek letter symbol (e.g., type δ to output δ or Δ to output a capital letter Δ). The following table provides an overview of Greek letter symbols.

Letter	Code	letter	code
Α	Α	α	α
Β	Β	β	β
Γ	Γ	γ	γ
Δ	Δ	δ	δ
Ε	Ε	ε	ε
Ζ	Ζ	ζ	ζ
Η	Η	η	η
Θ	Θ	θ	θ
Ι	Ι	ι	ι
Κ	Κ	κ	κ
Λ	Λ	λ	λ
Μ	Μ	μ	μ
Ν	Ν	ν	ν
Ξ	Ξ	ξ	ξ
Ο	Ο	ο	ο
Π	Π	π	π
Ρ	Ρ	ρ	ρ
Σ	Σ	σ	σ
Τ	Τ	τ	τ
Υ	Υ	υ	υ
Φ	Φ	φ	φ
Χ	Χ	χ	χ
Ψ	Ψ	ψ	ψ
Ω	Ω	ω	ω

Arrows and Operators

Arrows and operators can also be implemented as html symbols. The following table provides an overview.

	Arrows			Operators (1)			Operators (2)			Operators (3)
←	←		∀	∀		∗	∗		∼	∼
↑	↑		∂	∂		√	√		≅	≅
→	→		∃	∃		∝	∝		≈	≈
↓	↓		∅	∅		∞	∞		≠	≠
↔	↔		∇	∇		∠	∠		≡	≡
↵	↵		∈	∈		∧	∧		≤	≤
⇐	⇐		∉	∉		∨	∨		≥	≥
⇑	⇑		∋	∋		∩	∩		⊂	⊂
⇒	⇒		∏	∏		∪	∪		⊃	⊃
⇓	⇓		∑	∑		∫	∫		⊄	⊄
⇔	⇔		−	−		⋅	⋅		⊥	⊥

Miscellaneous Symbols

Markdown profits from many more html symbols that may be used in equations or other text. The following table provides an overview of such miscellaneous symbols.

	Symbols (1)			Symbols (2)			Symbols (3)
“	"		–	–		‾	‾
&	&		—	—		⁄	⁄
<	&lt;		‘	&lsquo;		ς	&sigmaf;
>	&gt;		’	&rsquo;		ℑ	&image;
Œ	&OElig;		‚	&sbquo;		ℜ	&real;
œ	&oelig;		“	&ldquo;		™	&trade;
Š	&Scaron;		”	&rdquo;		ℵ	&alefsym;
š	&scaron;		„	&bdquo;		⌈	&lceil;
Ÿ	&Yuml;		†	&dagger;		⌉	&rceil;
ˆ	&circ;		‡	&Dagger;		⌊	&lfloor;
˜	&tilde;		‰	&permil;		⌋	&rfloor;
	&ensp;		‹	&lsaquo;		⟨	&lang;
	&emsp;		›	&rsaquo;		⟩	&rang;
	&thinsp;		€	&euro;		◊	&loz;
‌	&zwnj;		•	&bull;		♠	&spades;
‍	&zwj;		…	&hellip;		♣	&clubs;
‎	&lrm;		′	&prime;		♥	&hearts;
‏	&rlm;		″	&Prime;		♦	&diams;

Wikis

While every git repository should at least contain a descriptive README.md, wiki s provide much more detail and guidance. Wikis are a convenient way to guide users with permanent sidebars (such as the menu bar on this website), help users to understand methods and codes, and collaborative coding with precise descriptions of scripts. GitHub users find options to activate wikis in the Settings tab of a repository and the developers continue to improve wiki functions (read more about GitHub’s wikis).

More sophisticated wikis are available on the Jekyll themes website (e.g., the git-wiki theme). To use Jekyll themes, make sure to enable GitHub pages (in the repository Settings tab) for the repository where you want to establish the wiki (this wiki-repository is typically another repository to describe a code-repository). Then, install the Ruby development environment and Jekyll (see instructions on their website to access and build hundreds of themes for code and project documentation. Forked and locally adapted themes can then be pushed to a remote wiki repository using git.

Tip

There are other git-services and wiki host providers out there, such as GitLab or plan.io.

Exercise

Get practice in markdown with the markdown and git exercise.

reStructuredText, Sphinx, and readthedocs

An alternative to markdown is reStructuredText that enables embedding Python docstrings (read more about Code Style and Conventions) in any script with Sphinx.

Without any Python or programming knowledge, it might be hard to get started with Sphinx. So make sure to understand Python basics and document any code with docstrings, at best using google style formatting. Once you start documenting your first Python package, Google-style docstrings will enable the fast generation of high-quality docs. Currently, one of the best options for partially auto-generating code documentations, for any programming language, is readthedocs, which builds on Sphinx and reStructuredText.