Documentation¶
Leonardo Da Vinci used journals to sketch, develop and eventually pass on his ideas. Alexand er 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 the way in which 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 - just take about 10 minutes to read how to save days.
What to document?¶
A 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 the software¶
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¶
This section should answer the following questions:
What system requirements are needed?
Which dependencies does the software have (e.g., other Python packages such as NumPy)?
What input data does a user need to run the software?
Installation¶
Describe step-by-step the installation of the software (e.g., how to download and access your Python package). Screenshots can be helpful here. At best, the Requirements section made it clear what users need to proceed with the installation.
Usage¶
Describe how the software can be used, starting with basics such as importing the software as Python package. Mention possible pre- and post-processing for input and output data, 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 is error-free and of course only the user makes mistakes. Show compassion and integrate specific try-except statements (more on the Pythonbasics page) in the source code, which point out possible error sources. These error (and maybe even warning) messages should all be listed in a Troubleshooting 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, it is very likely that any other author 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 on the code style page.
Markdown¶
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. Here is an example how Markdown works:
# 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 ...
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 loosing 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 ATOM (for combination with JavaScript, html, and CSS), and Jupyter Lab or PyCharm (for combination with Python or R), which both are available through Anaconda. Read more about Anaconda and associated IDEs on the previous pages.
Markdown command overview (+images)¶
The following table and sections provide an overview of basic markdown command s. There is much more options out there, which you can find by using your favorite search engine with the keywords markdown guide.
Feature |
Code |
Example |
|---|---|---|
Blockquote |
|
|
Bold text |
|
Bold |
Code block (inline) |
|
inline :lite ral:`code` |
Heading 1 |
|
Heading 1 |
Heading 2 |
|
Heading 2 |
Heading 3 |
|
Heading 3 |
Horizontal rule |
|
——- |
Hyperlink |
|
tsinfo.com>`__ |
Hyperlink to section |
|
`Link to apple-section tsinfo.com>`__ |
Image |
|
|
Italic text |
|
italic |
Numbered list item |
|
1. Numbered item |
Reference (defined) |
` [Defined Reference][wiki]` |
|
Reference (definition) |
|
Place at file bottom |
Strikethrough |
|
[STRIKEOUT: Strikethrough] |
Itemization (un-numbered list)¶
Itemized list section can be produced using *, +, or - symbols with tabs that determine the list indentation:
* level 1 item
- level 2 item
- another level 2 item
+ level 3 item
* next level 1 item
- 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).
| Fruit | Kingdom | Genus |
|-------|:-------:|------:|
|Banana | Plantae | Musa |
|Jackfruit|Plantae|Artocarpus|
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}">
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.
Math expressions: Greek letters¶
In order 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 |
|---|---|---|---|
Α |
|
α |
|
Β |
|
β |
|
Γ |
|
γ |
|
Δ |
|
δ |
|
Ε |
|
ε |
|
Ζ |
|
ζ |
|
Η |
|
η |
|
Θ |
|
θ |
|
Ι |
|
ι |
|
Κ |
|
κ |
|
Λ |
|
λ |
|
Μ |
|
μ |
|
Ν |
|
ν |
|
Ξ |
|
ξ |
|
Ο |
|
ο |
|
Π |
|
π |
|
Ρ |
|
ρ |
|
Σ |
|
σ |
|
Τ |
|
τ |
|
Υ |
|
υ |
|
Φ |
|
φ |
|
Χ |
|
χ |
|
Ψ |
|
ψ |
|
Ω |
|
ω |
|
Math expressions: Arrows and Operators¶
Arrows and operators can also be implemented as html symbols. The following table provides an overview.
Miscellaneous Symbols¶
Markdown profits from many more html symbols that may be used in equations or other text. The following table provides an overview over such miscellaneous symbols.
Symbols (1) |
Symbols (2) |
Symbols (3) |
|||
|---|---|---|---|---|---|
“ |
|
– |
|
‾ |
|
& |
|
— |
|
⁄ |
|
< |
|
‘ |
|
ς |
|
> |
|
’ |
|
ℑ |
|
Π|
|
‚ |
|
ℜ |
|
œ |
|
“ |
|
™ |
|
Š |
|
. |
|
ℵ |
|
š |
|
„ |
|
⌈ |
|
Ÿ |
|
† |
|
⌉ |
|
ˆ |
|
‡ |
|
⌊ |
|
˜ |
|
‰ |
|
⌋ |
|
. |
|
‹ |
|
⟨ |
|
. |
|
› |
|
⟩ |
|
. |
|
€ |
|
◊ |
|
. |
|
|
♠ |
|
|
. |
|
… |
|
♣ |
|
. |
|
′ |
|
♥ |
|
. |
|
″ |
|
♦ |
|
Wikis¶
While every git repository should at least contain a descriptive README.md, wikis provide much more detail and guidance. Wikis are a convenient way to guide users with permanent side bars (such as the menu bar on this web site), 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 web site (e.g., the git-wiki theme). In order 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 in order to describe a code-repository). Then, install the Ruby development environment and Jekyll (see instructions on their website) in order 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.
Exercise
Get practice in markdown with the markdown & git exercise.
reStructuredText, Sphinx and readthedocs¶
An alternative to markdown is reStructuredText that enables embedding Python docstrings (read more in the code style conventions) of any script or module 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.