[Swift-devel] Swift Documentation

[David Kelly]

Hello all,

Just wanted to send a quick update on the status of the swift documentation.
Starting with trunk, all website documentation is kept in the swift/docs
directory. Everything is in asciidoc format and will get converted to HTML
and PDF. More information about how to use asciidoc can be found at
http://www.methods.co.nz/asciidoc.

Currently in this directory are the userguide, tutorial, cookbook and
something I created called the newuser guide. The newuser guide should
probably be renamed because it's slightly confusing - it's not a replacement
for the userguide, it's a guide for new users. It's still a work in progress
and needs to be put together, but there are bits and pieces there. It will
contain information on how to set up Swift in specific environments. Right
now there is info for how to run on PADS, Fusion, and Beagle. It gives
information on how to request an account, which queues to use, setting your
projects, how to set up sites.xml, use gensites, and any other specific
information about how to get Swift up and running in that environment.

To build the guides, run:

$ swift/docs/build_docs.sh <directory_to_install_into>

This script assumes that you have asciidoc already installed. You can edit
the build_docs.sh script to change information about ownership and file
permissions of the HTML and PDF output files as needed.

When you want to make a change to the documentation, make your changes
directly to the files in your swift/docs directory. The guides are split
into chapters. Chapters are located in the same directory as the guide but
do not have a file extension. Please build your documents and take a look at
the output before committing. As of tonight, there is a cron job running
under my account that will update the website nightly. It runs the
build_docs.sh script every night at 7pm on communicado.

If there is an important change that needs to be updated sooner, you can
also manually update the website. From one of the CI machines, run:

$ swift/docs/build_docs.sh /ci/www/projects/swift/guides

Manual updates require that you a member of the vdl2-svn group. If you are
not a member of this group, you can request access by mailing
support at ci.uchicago.edu.

I'll write a more detailed guide about this at some point (perhaps an update
to the maintaining swift web content on the wiki), but just wanted to get
this info out for now. Let me know if you have any questions or run into
issues with it.

Thanks,
David
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/swift-devel/attachments/20110623/27af0d45/attachment.html>