4 Using Markdown for Documentation

Search in book...
Toggle Font Controls
Create new playlist

Name your new playlist

Playlist description (optional)
Sign In

Email address

Password

Forgot Password?

or

Continue with Facebook

Continue with Google
Sign Up

Full Name

Email address

Confirm Email Address

Password

or

Continue with Facebook

Continue with Google

4
Using Markdown for Documentation

As a data scientist, you will often encounter the somewhat trivial task of adding formatting to plain text (e.g., making it bold or italic) without the use of a program like Microsoft Word. This chapter introduces Markdown, a simple programming syntax that can be used to describe text formatting and structure by adding special characters to the text. Being comfortable with this simple syntax to describe text rendering will help you document your code, and post well-formatted messages to question forums (such as StackOverflow¹) or chat applications (such as Slack²), as well as create clear documentation that describes your code’s purpose when hosted on GitHub (called the “README” file). In this chapter, you will learn the basics of Markdown syntax, and how to leverage it to produce readable code documents.

¹StackOverflow: https://stackoverflow.com

²Slack: https://slack.com

4.1 Writing Markdown

Markdown³ is a lightweight syntax that is used to describe the format and structure of text documents. With only a small handful of options, Markdown allows you to apply formatting to your text (such as making text bold or italic), as well as to provide structure to a document (such as headers or bullet points). Mastering the basics of writing Markdown will allow you to quickly and easily create well-formatted documents.

³Markdown: Syntax original specification by John Gruber: https://daringfireball.net/projects/markdown/syntax

Fun Fact

Markdown belongs to a family of programming languages used to describe document formatting known as markup languages (confusing, right?). For example, HTML (HyperText Markup Language) is used to describe the content and format of websites.

Additional Fun Fact: This book was written in Markdown!

4.1.1 Text Formatting

At its most basic, Markdown is used to declare text formatting options. You do this by adding special symbols (punctuation) around the text you wish to “mark.” For example, if you want text to be rendered (displayed) in italics, you would surround that text with underscores (_): you would type _italics_, and a program would know to render that text as italics. You can see how this looks in Figure 4.1.

A screenshot represents markdown text formatting. — Figure 4.1 Markdown text formatting. The code version is on the left; the rendered version is on the right.

The code version on the left reads, This is a paragraph in which we'll add **bold text**, _italicized text_, and 'code' into the middle of a sentence. The rendered version on the right reads, This is a paragraph in which we'll add bold text, italicized text, and code into the middle of a sentence. The phrase bold text is in bold, the word italicized is italicized, and the word code is in a font different from the rest of the text.

There are a few different ways you can format text, as summarized in Table 4.1.

Table 4.1 Markdown text formatting syntax

Syntax	Formatting
`_text_`	emphasize (italicize) using underscores (`_`)
`text`	strongly emphasize (bold) using two asterisks (`*`)
`text`	`code` style using backticks (`)
`~~text~~`	strike-through using two tildes (`~`)

While there are further variations and syntax options, these are the most common.

4.1.2 Text Blocks

Markdown isn’t just about adding bold and italics in the middle of text; it also enables you to create distinct blocks of formatted content (such as a header or a chunk of code). You do this by adding a symbol in front of the text. For example, in Figure 4.2, the document (shown on the right) is produced using the Markdown syntax (shown on the left) described in Table 4.2.

A screenshot represents markdown block formatting and the output rendered. — Figure 4.2 Markdown block formatting. Code (left) and rendered output (right).

The code on the left reads, # Top Level Header ## Second Level Header Here is a regular paragraph, followed by a list: - Item 1 - Item 2 - Item 3 You can also have a block of code, as shown here: ``` block of code across multiple lines ```. The rendered output on the right reads, Top Level Header (in thick, bold font). Second Level Header (in thick, bold font, the size smaller than the top level header). (the rest are in normal font size) Here is a regular paragraph, followed by a list: Item 1 Item 2 Item 3 You can also have a block of code, as shown here: block of code across multiple lines. The block of code is shown separately, enclosed within a block.

Table 4.2 Markdown block formatting syntax

Syntax	Formatting
`#`	Header (use `##` for second level, `###` for third level, etc.)
```	Code section (three backticks) that encapsulate the code
`-`	Bulleted/unordered lists (hyphens)
`>`	Block quote

4.1.3 Hyperlinks

Providing hyperlinks in documentation is a great way to reference other resources on the web. You turn text into a hyperlink in Markdown by surrounding the text in square brackets [], and placing the URL to link to immediately after that in parentheses (). Here’s an example:

Click here to view code image

[text to display](https://some/url/or/path)

The text between the brackets (“text to display”) will be displayed in your document with hyperlink formatting. Clicking on the hyperlink will direct a web browser to the URL in the parentheses (https://some/url/or/path). Note that hyperlinks can be included inline in the middle of a paragraph or list item; the text to display can also be formatted with Markdown to make it bold or italic.

While the URL is most commonly an absolute path to a resource on the web, it can also be a relative path to another file on the same machine (the file path is relative to the Markdown document that contains the link). This is particularly useful for linking from one Markdown file to another (e.g., if the documentation for a project is spread across multiple pages).

4.1.4 Images

Markdown also supports the rendering of images in your documents, which allows you to include diagrams, charts, and pictures in your documentation. The syntax for including images is similar to that for hyperlinks, except with an exclamation point ! before the link to indicate that it should be shown as an image:

Click here to view code image

![description of the image](path/to/image)

When shown as an image, the “text to display” becomes an alternate text description for the image, which will be shown if the image cannot be shown (e.g., if it fails to load). This is particularly important for the accessibility of the documents you create, as anyone using a screenreader can be read the description provided in place of the image.

As with hyperlinks, the path to an image can be an absolute path (for referencing images on the web), or a relative path to an image file on the same machine (the file path is relative to the Markdown document). Specifying the correct path is the most common problem when rendering images in Markdown; make sure to review paths (Section 2.2.3) if you have any trouble rendering your image.

4.1.5 Tables

While syntax for tables isn’t supported in all Markdown environments, tables can be shown on GitHub and in many other rendering engines. Tables are useful for organizing content, though they are somewhat verbose to express in markup syntax. For example, Table 4.2 describing Markdown syntax and formatting was written using the following Markdown syntax:

Click here to view code image

| Syntax        | Formatting                                                       |
| :-------------| :--------------------------------------------------------------- |
|`#`            | Header (use `##` for second level, `###` for third level, etc.)  |
| ```` ``` ```` | Code section (3 backticks) that encapsulate the code             |
|`-`            | Bulleted/unordered lists (hyphens)                               |
|`>`            | Block quote                                                      |

This is known as a pipe table, as columns are separated with the pipe symbol (|). The first line contains the column headers, followed by a line of hyphens (-), followed by each row of the table on a new line. The colon (:) next to the hyphens indicates that the content in that column should be aligned to the left. The outer pipe characters and additional spaces in each row are optional, but they help keep the code easy to read; it isn’t required to have the pipes line up.

(Note that in the table the triple backticks used for a code section are surrounded by quadruple backticks to make sure that they are rendered as the ` symbol, and not interpreted as a Markdown command!)

For other Markdown options—including blockquotes and syntax-colored code blocks—see, for example, this GitHub Markdown Cheatsheet.⁴

⁴Markdown Cheatsheet: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

4.2 Rendering Markdown

To view the rendered version of your Markdown-formatted syntax, you need to use a program that converts from Markdown into a formatted document. Luckily, this often happens automatically with systems that leverage Markdown. For example, GitHub’s web portal will automatically render Markdown files (which have the extension .md), and Slack and StackOverflow will automatically format your messages.

Indeed, the web portal page for each GitHub repository will automatically format and display as project documentation the Markdown file called README.md (it must have this name) stored in the root directory of the project repo. The README file contains important instructions and details about the program—it asks you to “read me!” Most public GitHub repositories include a README that explains the context and usage of the code in the repo. For example, the documentation describing this book’s exercises is written in this README.md file,⁵ with individual folders also having their own README files to explain the code in those specific directories.

⁵See https://github.com/programming-for-data-science/book-exercises/blob/master/README.md

Caution

The syntax may vary slightly across programs and services that render Markdown. For example, Slack doesn’t technically support Markdown syntax (though it is very similar to Markdown). GitHub in particular has special limitations and extensions to the language; see the documentation^a for details or if you run into problems.

^a https://help.github.com/categories/writing-on-github/

However, it can be helpful to preview your rendered Markdown before posting code to GitHub or StackOverflow. One of the best ways to do this is to write your marked code in a text editor that supports preview rendering, such as Atom.

To preview what your rendered content will look like, simply open a Markdown file (.md) in Atom. Then use the command palette⁶ (or the shortcut ctrl+shift+m) to toggle the Markdown Preview. Once this preview is open, it will automatically update to reflect any changes to the Markdown code as you type.

⁶Atom Command Palette: http://flight-manual.atom.io/getting-started/sections/atom-basics/#command-palette

Tip

You can use the command palette to Toggle Github Style for the Markdown preview; this will make the rendered preview look (mostly) the same as it will when uploaded to GitHub, though some syntactical differences may still apply.

Other options for previewing rendered Markdown include the following:

Many editors (such as Visual Studio Code⁷) include automatic Markdown rendering, or have extensions to provide that functionality.

⁷Visual Studio Code: https://code.visualstudio.com
Stand-alone programs such as MacDown⁸ (Mac only) will also do the same work, often providing nicer-looking editor windows.

⁸MacDown: Markdown editor (Mac Only): http://macdown.uranusjr.com
There are a variety of online Markdown editors that you can use for practice or quick tests. Dillinger⁹ is one of the nicer ones, but there are plenty of others if you’re looking for something more specific.

⁹Dillinger: online Markdown editor: http://dillinger.io
A number of Google Chrome Extensions will render Markdown files for you. For example, Markdown Reader¹⁰ provides a simple rendering of a Markdown file (note it may differ slightly from the way GitHub would render the document). Once you’ve installed the extension, you can drag-and-drop a .md file into a blank Chrome tab to view the formatted document. Double-click to view the raw code.

¹⁰Markdown Reader extension for Google Chrome: https://chrome.google.com/webstore/detail/markdownreader/gpoigdifkoadgajcincpilkjmejcaanc?hl=en
If you want to render (compile) your markdown to a .pdf file, you can use an Atom extension¹¹ or a variety of other programs to do so.

This chapter introduced Markdown syntax as a helpful tool for formatting documentation about your code. You will use this syntax to provide information about your code (e.g., in git repository README.md files), to ask questions about your code (e.g., on StackOverflow), and to present the results of your code analysis (e.g., using R Markdown, described in Chapter 18). For practice writing Markdown syntax, see the set of accompanying book exercises.¹²

¹¹Markdown to PDF extension for Atom: https://atom.io/packages/markdown-pdf

¹²Markdown exercises: https://github.com/programming-for-data-science/chapter-04-exercises

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.

Table of Contents for 4 Using Markdown for Documentation

Create new playlist

Sign In

Sign Up

4Using Markdown for Documentation

4.1 Writing Markdown

4.1.1 Text Formatting

4.1.2 Text Blocks

4.1.3 Hyperlinks

4.1.4 Images

4.1.5 Tables

4.2 Rendering Markdown

Table of Contents for
4 Using Markdown for Documentation

4
Using Markdown for Documentation