Tutorial

This tutorial shows how the Enki text editor, integrated with the CodeChat literate programming plug-in, provides a powerful environment for creating expressive programs.

The following playlist covers all the topics in this tutorial.

This tutorial employs the following typography:

  • This font for the name of a file or directory;
  • This font for labels in the GUI; and
  • This font for menu selections.

Basic restructuredText

CodeChat relies on reStructuredText (reST) in comments to provide human-readable markup. “ReStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax” [1]. So, this tutorial begins by exploring reST using Enki.

First, install Enki, which hosts the CodeChat system. Next, download the source code for CodeChat, which also contains a reStructuredText Primer needed in this tutorial. Unzip this file in a directory of your choice. Now, open location of unzipped CodeChat files/docs/rest-primer.rst in Enki. Move around the document, noticing that the text and web views are automatically synchronized [2]. Click on any element of the web view to show the corresponding text view. Edit – your changes are visible immediately. Note that the syncronization ability applies to any file Enki can preview, such as HTML files (try location of unzipped CodeChat files/CodeChat/LICENSE.html, for exampe, or Enki’s README.md).

Now, explore creating your own reST file: create a new file, then save it with an extension of .rst. Based on the very helpful reST primer, try out some syntax: create headings, include a hyperlink, add an image, use inline markup. When errors occur, they are reported in the log window and typically in-line in the resulting web page. When a page is complete, the save icon in the preview window stores the resulting HTML to disk.

By design, reST operates on one file at a time. To create a web site consisting of multiple, interlinked documents, we turn to Sphinx, wihch adds this ability to reStructuredText.

[1]http://docutils.sourceforge.net/rst.html
[2]Assuming TRE is installed. Follow the TRE build instructions if not.

Basic Sphinx

“Sphinx is a tool that makes it easy to create intelligent and beautiful documentation” [3]. It provides additional features lacking basic reStructuredText, including the ability to link together many documents (such as all the files in a program’s source code).

To use Sphinx with Enki, first go to Settings ‣ Settings ‣ Sphinx. Then enable Sphinx and select location of unzipped CodeChat files as the project directory. Click OK. Then, open location of unzipped CodeChat files/README.rst. The resulting web page will be displayed in the Preview dock.

In addition to providing a number of beautiful themes for rendering reST files, Sphinx creates a set of linked documents. To see this in action, open location of unzipped CodeChat files/index.rst. This file determines the hierarchical document structure. For example, the following markup includes headings from README.rst into index.rst:

.. toctree::
   :maxdepth: 2

   README.rst

One important note: when refering to files in subdirectories, a forward slash MUST be used, even on Windows. That is, use CodeChat/filename, not CodeChat\filename. Sphinx supports many other markup constructs as well.

Creating a new project

To create a new Sphinx project, first create an empty directory to hold your project’s files. In Settings ‣ Settings ‣ Sphinx, select this directory as the project directory then click OK. In Settings ‣ Settings ‣ Literate programming, uncheck Enable CodeChat; otherwise, Enki will create not just a Sphinx project, but a CodeChat-enabled Sphinx project. Next, create a new file and save it with the .rst extension in the empty directory you created. A dialog box will pop up, asking if you’d like some default files copied. Click yes. Open the generated index.rst file. Add some content to this file, including at least one heading, but notice that it generates a warning in the log window. To fix this, include it in your Sphinx project: in index.rst add it to your toctree directive. Assuming the name of the file you created was demo.rst, the syntax is:

.. toctree::
   :maxdepth: 2

   demo.rst

When you switch back to demo.rst, it will now be included in your project.

[3]http://sphinx-doc.org/index.html

Basic CodeChat

Based on your familiarity with reST, we’ll now explore embedding reST in the comments of a program. First, enable CodeChat in Enki’s Settings ‣ Settings ‣ Literate Programming dialog by checking the “Enable CodeChat” checkbox. In Settings ‣ Settings ‣ Sphinx, uncheck the Enable Sphinx checkbox. Now, open location of unzipped CodeChat files/setup.py. Notice that reST markup, when correctly embedded in comments, renders properly. Specifically, to be rendered using reST:

  1. A comment must be placed on a line containing only comments or whitespace, but no code, preprocessor directives, etc.
  2. One space must follow the opening comment delimiter.

The style_guide.cpp - Style recommendations for CodeChat gives more details; also, see CommentDelimiterInfo.py - Info on comment delimiters for many languages. for a full list of supported languages.

Now, open one of your source files. Modify your comments to add reST markup; add in titles, hyperlinks, and other useful markup.

While basic CodeChat usage shown here provides a quick way to begin experimenting with literate programming, it’s limited in several ways. First, because it uses basic reST, CodeChat lacks the ability to create a web of documentation over multiple source files in a project. Second, the web page produced by CodeChat must be manually saved to disk for others to view, an inefficient process when providing documentation to others. Finally, the results are rather plain. We therefore turn to Sphinx to remedy all these problems.

Basic Sphinx with CodeChat

Now, combining Sphinx with CodeChat enables the use of the literate programming paradigm applied to all source and accompanying documentation in a project. To see this in action, in Settings ‣ Settings ‣ Sphinx enable Sphinx; make sure the project directory is location of unzipped CodeChat files/. Now, open or switch to location of unzipped CodeChat files/setup.py. Note that the source code is rendered to HTML for this file and for all source and documentation files in the CodeChat project.

Now, create a new Sphinx with CodeChat project. First, choose a directory in which source files you’d like to document reside. In Settings ‣ Settings ‣ Sphinx, select this direectory. After pressing OK, Enki will ask if you’d like to add the necessary template files; click OK. These files are different than the Sphinx-only template files from earlier, since both Sphinx and CodeChat are enabled. Now, transform your program into a document by adding titles, hyperlinks, etc. Explore the conf.py file, added as a template, to customize the output for your needs.

Reference

With a basic knowledge of this literate programming system, the following pages provide helpful reference information.

Also, refer to the Examples to see some of the ways in which CodeChat helps create beautiful programs.