[Swift-devel] Swift Documentation

[Michael Wilde]

David, thanks, this is great. 


I tried build_docs.sh and note a few things (which I and others should fix): 
- We need a disclaimer of "under construction" on the cookbook 
- The cookbook isnt getting section numbered, and has a format problem in the Beagle section, step 4. 
- build_docs.sh should leave top-level links in the top-level directory below the destination dir. Currently all the doc roots are left deep below a trunk/ subdir palced in the dest dir. 
- the build processes seems to need dblatex for making pdfs - need to note and point to an install package for needed tools 


Nice work! 


- Mike 



----- Original Message -----


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 

_______________________________________________ 
Swift-devel mailing list 
Swift-devel at ci.uchicago.edu 
https://lists.ci.uchicago.edu/cgi-bin/mailman/listinfo/swift-devel 



-- 
Michael Wilde 
Computation Institute, University of Chicago 
Mathematics and Computer Science Division 
Argonne National Laboratory 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/swift-devel/attachments/20110624/13dff196/attachment.html>