Documentation in Python¶
Writing is an important job not just for writers, but also for researchers and developers. Your academic findings will not be particularly useful if no one else has access to them, or can not understand them. Similarly, if you develop some great new piece of software to solve some problem, but don’t document and distribute it, then no one will use it.
Clear communication and documentation are crucial aspects of scientific computing. We’ll take a quick look at how this manifests in Python, and given enough time, we’ll return to the topic later.
Documentation suitable for the web¶
The internet is the most common hub for the distribution of software. Similarly, it is the most common place to provide support and host documentation. However, developing for the web requires a skill set that is largely orthogonal to that of scientific computing. Without a few key tools, hosting online documentation could be even more cumbersome than developing the software itself!
One nice tool for this, particularly for Python, is Sphinx. This tool supports many languages other than just Python. It falls into the class of static site generators.
This whole website was created using Sphinx and reStructuredText (discussed below).
Markdown¶
The Markdown language can be an antidote for these problems. Markdown is not a programming language, but rather a formatting standard on plain text. The main goal of Markdown is to write an easy to read document “as-is”, that can alse be converted into HTML, or other fancier formats, easily and unambiguously. Consider this sample document:
Heading
=======
## This is a sub-heading
### This is a sub-sub-heading
This is a paragraph. If you want to make
another one, just make a blank line.
This is a second paragraph. The new line
will be ignored,
but if you want to make it by force,
just make two spaces
at the end of the line.
You can make an *italic*, **bold** or `monospace` texts.
This is a bullet list
* apples
* oranges
* pears
And numbered list:
1. wash
2. rinse
3. repeat
A [link](http://example.com).
Now, its way better. The Markdown text is very easy to read, and easy to write.
Also, since the Markdown text is just a plain text, it is a very portable format
which can be imported to other programs or services easily. For example, most
of the popular remote hosts for git repositories support README’s written in
markdown. This makes them simultaneously simple plaintext files (which is good for
git), and allows fancy rendering when on the website. Typically this is achieved
by naming it README.md.
In other settings, publishing your markdown document on the web requires you to convert the markdown file into HTML. By writing a markdown document you won’t need to think about the final HTML syntax (or whatever format you choose).
reStructuredText¶
reStructuredText is another markup language, which widely used on the Python community to document Python projects. For example, the Python documentation pages were written in reStructuredText and processed with Sphinx.
Note
These AM 129 lecture notes are also created in this way
The basic syntax for reStructuredText is very similar to markdown.
===============
This is a title
===============
This is the first section
-------------------------
This is a paragraph. New lines
will be ignored, and words will wrap according to whatever other
formats are converted to. You can start another paragraph
by making a blank line. You can write in
*italic*, **bold**, `monospace` text.
bullet list:
* apple
* oranges
* pears
And numbered list:
#. wash
#. rinse
#. repeat
A `link <http://example.com>`_.
At a glance, the differences between markdown and reStructuredText are hardly noticeable. Broadly speaking, markdown is useful primarily for targeting the web, with other output formats being more of an afterthought. reStructuredText is a little more friendly to technical writing, and has more natural support for things like mathematical expressions using LaTex.
To read more on the differences between markdown and reStructuredText, refer to this article.
Conversion tools¶
You can convert markdown or reStructuredText into a variety of other formats, in particular as statically generated websites. There are many tools, such as pandoc, docutils, sphinx or pelican.
Sphinx, the tool that has been used for making these online lecture notes, can generate a static website from a set of markdown or reStructuredText files. To make a Sphinx web page, you first need to install the Sphinx package.
$ pip install sphinx
Sphinx is a Python package, so you’ll need to use pip to install it.
Let’s use Sphinx to create a simple website. Open your terminal and navigate
to a directory where you would like to store your website and the associated
sources. Then you can run:
$ sphinx-quickstart
upon which you will see questions regarding the initial configuration that you’ll
need to answer. This will create a source directory with conf.py and a master
document called index.rst. Don’t know what to answer? Don’t be afraid, there are
default answers at the end of the questions, and you can always go with them first
and fix them later by editing the conf.py file.
If you open index.rst file you should see something similar to:
.. test documentation master file, created by
sphinx-quickstart on Thu Oct 31 00:45:12 2030.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to test's documentation!
================================
.. toctree::
:maxdepth: 2
:caption: Contents:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
This reStructuredText file will get processed into the landing page for your website. To have Sphinx process this into a statically generated HTML site you can run:
$ make html
Then, Sphinx will generate some HTML files in _build/html directory.
If you open the index.html file on your web browser (such as Chrome, Safari or Firefox)
then you can see a web-formatted document.
