Documenting Your Project With |RST| ################################### .. vim:ft=rst spell: .. include:: /references.inc .. wordcount:: You absolutely should be writing documentation at the same time you write code. No, I do not mean add comments to your code! I mean write a separate document that *explains* your code to some poor soul who will inherit your creation and have to "maintain" it. You need to establish a habit of working on your documentation, and treat that as something as important as the code itself! Good Documentation ****************** What makes for good documentation? For one thing, it is designed to convey information to the reader. But who is that reader? Perhaps it is you a week from now, when you have forgotten why you did what you did. Most certainly, it is another developer who inherits your code a year from now, when you are not around to help out. Maybe you are working on another project, maybe you have left the company. Who knows? `Donald Knuth`_, one of the most respected computer scientists this country has produced, thought this was so important, he proposed a new way of programming he called `Literate Programming`_. In his system, you wrote the source code for a book, describing the code you were developing. That code was processed using another great tool developed by Knuth_, the TeX_ typesetting system, and generated something a published could use to print a real book (or, today, a nice PDF). Where is the code you need to compile? It is buried in the documentation source, and extracted by a tool designed to generate the code file the compiler could process. Knuth_ was concerned that documentation and code might wander in different directions, so he made is hard for humans to read the generated code. The compiler could care less, so Knuth_ hoped that developers would stay focused on writing the "literate" documentation instead. Knuth's system never really took off, but it became part of the programming landscape, and still has many proponents (including me)! Writing Documentation ********************* To get you started in writing this documentation, I am going to have you use a very popular system for processing your documentation into something easy to read. Shoot, you are reading the product of that system right now. I have been using this tool for my lecture notes ever since it hit the planet in 2008! The tool we will use is Sphinx_, a Python tool that has a huge following now. Although it was designed to support documenting the Python project, itself, developers are using it for all kinds of projects, not just Python projects. Prerequisites ============= In order to use Sphinx_, you need to have Python installed, and a support tool used to install Python libraries: PC Setup -------- On a PC, install the latest release of Python_ from the project website. Mac Setup --------- On a Mac, using ``HomeBrew``, installing Python_ is as easy as this: .. code-block:: bash $ brew install python3 Of course, you can use the installer, also available on the project website. Linux Setup ----------- On a Ubuntu_ Linux system, the needed tools are installed like so: .. code-block:: bash $ sudo apt-get install python3 $ sudo apt-get install python3-pip Verify Tools ------------ Check your setup on any system by running these commands from the command line: .. code-block:: bash * python --version Python 3.6.5 $ pip --version pip 9.0.3 .. note:: I needed to update ``pip`` on my system, which I did by doing this: .. code-block:: bash $ pip install --upgrade pip Documentation Setup =================== The first thing you need to do is set up a folder for your documentation. The usual home I set up for this is a ``rst`` folder at the root of your project folder. The web pages we produce will be created in another folder named ``docs``. By doing this, you can get a website for free for your project from GitHub_ (see below). .. code-block:: bash $ cd $ mkdir rst $ mkdir docs Installing Tools ---------------- With ``pip`` installed, it is common to create a file named ``requirements.txt`` where you list the libraries you need. For my Python projects, my ``requirements.txt`` file looks like this: .. literalinclude:: code/requirements.txt :linenos: :caption: requirements.txt With this file in place, run this command to install everything needed: .. code-block:: bash $ pip install -r requirements.txt .. note:: You can install things manually by doing this instead: .. code-block:: bash $ pip install sphinx $ pip install sphinx-rtd-theme The Sphinx_ tool is just a Python_ application. The ``sphinx-rtd-theme`` includes code needed to style your website. I an currently using the theme used on ``Read The Docs``, a popular website where developers put their project documentation. We will not use that system. Instead, we will publish our documentation on GitHub_. Initialize Documentation ------------------------ Sphinx uses a simple python configuration file to manage its operation. You can get a baasic starter setup easily by doing this: .. code-block:: bash $ cd rst $ sphinx-quickstart That above command will set up the SPhinx_ project. You will be asked a bunch of questions, most of which you can just leave as the default answer (except for your name and the project name). Add the Theme ------------- Before we can use the ``RTD`` theme, we need to modify the ``conf.py`` file a bit. Here is a stripped down version of the file I actually use for most projects: .. literalinclude:: code/conf.py :linenos: :caption: rst/conf.py Running Sphinx ============== To test your setup, or to build your documentation, open a command line in your ``docs`` folder, and do this: .. code-block:: text $ make html You should find a new folder, ``docs/_build``. In that folder you will have a ``html`` folder. Open up the ``index.html`` file you find there with your browser to see your nicely formatted documentation. You can learn more about using Sphinx_ from the project website, or look around on GitHub_ for examples. My class notes are all done using this tool.