Tutorial

This tutorial shows how the Visual Studio Code text editor, integrated with the CodeChat extension, provides a powerful environment for creating expressive programs. The CodeChat System supports several other renderers as well.

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 the CodeChat System.

First, install and run the CodeChat Server and install the Visual Studio Code CodeChat extension. Next, download the the CodeChat reST tutorial. Open this file in Visual Studio Code, then open CodeChat. Edit the text – your changes are visible immediately.

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 in-line in the resulting web page.

Basic CodeChat

Based on your familiarity with reST, we’ll now explore embedding reST in the comments of a program. To do this, download and open CodeChat’s setup.py. Note the format used for comments that will 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 with reStructuredText markup gives more details; 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.

Sphinx

“Sphinx is a tool that makes it easy to create intelligent and beautiful documentation” [2]. 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 the CodeChat System, first download and unzip the source code for CodeChat, which provides a example Sphinx project. Open README.rst from the unzipped files; the CodeChat System will render the project. Most of the files in this project will render. Make a few edits; note that you must save the file before the render takes place. Open a source file and make a few edits, again saving to render the edits.

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 referring 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 Sphinx project

To create a new Sphinx project, copy the files in the Sphinx template directory to a new directory. Open the file index.rst in this new directory; the new project is ready and will render.

Next, create a new file and save it with the .rst extension in the empty directory you created. 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.

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.