.. _ch03-python-documentation: ======================= 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. .. _ch03-html: 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). .. _ch03-md: 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: .. code-block:: md 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). ![Image](Image_icon.png) 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). .. _ch03-rst: 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. .. code-block:: rst =============== 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 `_. 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. .. code-block:: console $ 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: .. code-block:: console $ 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: .. code-block:: rst .. 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: .. code-block:: console $ 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.