Table of Contents

Overview

This guide provides a brief overview of how Swift Document Generation works. It should explain the structure of a docs directory, how to manually build documentation, and explain how document automation works.

Structure

A specific file and directory structure is required for each document in order to ease the process of automation, conversion, and copying.

Directories

Each subdirectory within docs/ should correspond to the name of the document. This name will also later be used in the URL used to point to the document.

Example Directory Names
docs/userguide
docs/tutorial

AsciiDoc File

Every document directory should contain one file with a .txt extension. This .txt file is the AsciiDoc document that later gets converted to various formats.

Example AsciiDoc Documents
docs/userguide/userguide.txt
docs/tutorial/tutorial.txt

Chapters

Each document directory should contain individual chapters that make up the document. These chapters should not have any file extensions.

Example Chapters
docs/userguide/overview
docs/userguide/language
docs/userguide/mappers
docs/userguide/commands

Including Chapters in a Document

The .txt file should then include the individual chapters with the AsciiDoc include command.

userguide.txt
include::overview[]

include::language[]

include::mappers[]

include::commands[]
Warning Be sure to include spaces between includes. Putting them together with no spaces can cause formatting/compilation errors.

Building Documentation Manually

Before committing anything to SVN, it is a good idea manually build the documentation for testing purposes.

Prerequisites

There are several prerequisites for building documentation:

For CI users, compiled versions of these packages can be found in ~davidk.

build_docs.sh

The script to build the documentation is docs/build_docs.sh. This script will convert the documents into HTML and PDF, and then copy the files to a given output directory.

Usage
./build_docs.sh /path/to/copy/output

Document Automation

All .txt files in the docs directory get converted to HTML and PDF on a nightly basis. These documents then get copied to the Swift web site.

Cron Job

The job that processes these documents runs on Bridled at 7pm nightly. The script is /home/davidk/docscripts/update_and_build.sh. The script calls svn update on several different swift directories in ~davidk, and then builds the the documents. The documents should be built for each Swift branch later than 0.93, including trunk. As new versions of Swift are created, this script will need to be updated.

Website

Once the cron job runs, documents can be accessed at:

http://www.ci.uchicago.edu/swift/guides/release-<version>/documentname/documentname.html http://www.ci.uchicago.edu/swift/guides/release-<version>/documentname/documentname.pdf

For example, assume that you create a document called docs/newdoc. You check this guide into Swift 0.93. The AsciiDoc .txt file is called newdoc.txt. The URLs that would be generated would be:

http://www.ci.uchicago.edu/swift/guides/release-0.93/newdoc/newdoc.html http://www.ci.uchicago.edu/swift/guides/release-0.93/newdoc/newdoc.pdf

home