[Swift-devel] Re: Website documentation

[David Kelly]

I have a basic version of the script for generating website docs
in /ci/www/projects/swift/guides. It works in a pretty similar way to what
we have now - the documents must manually be copied to
asciidocs/docs/<release>/*.txt and then the script converts the txt files to
html and pdf. Instead of having to copy the files manually, I think the next
step would be to have it generate these from releases using svn. I will add
this to the wiki once it gets a little more finalized. I am also working on
some improvements to the documents themselves. The asciidoc version of the
tutorial brings in the contents of external .swift scripts when generating
the html. Changes to the example scripts should automatically be referenced
in the tutorial. I will also try add something like dynamically generating
the properties into the user guide as was suggested, as well as other
various clean up and fixes.

David

On Wed, May 4, 2011 at 6:33 PM, Michael Wilde <wilde at mcs.anl.gov> wrote:

> Nice job, David!  This really looks great. Awesome, in fact, for a first
> cut.
>
> One thing that jumped out at me: in the swift.properties section:
>
> - the actual descriptions should be in plain text, not fixed width text
>
> - to keep the descriptions in sync with the sample/default swift.properties
> file in etc/, perhaps the sample file could be coded in such a way that we
> can grep the properties out in a "doc build" process that runs as part of
> ant or make, and automatically include them in the users guide.
>
> - Perhaps move the properties to an appendix rather than a chapter - the
> chapter could just talk about how to manage properties, and what the general
> "families" of properties are.
>
> Mike
>
>
> ------------------------------
>
> Hello,
>
> I just finished the preliminary version of the user guide in asciidoc. It
> is at http://www.ci.uchicago.edu/~davidk/userguide.html. The asciidoc
> source is at http://www.ci.uchicago.edu/~davidk/userguide.txt.
>
> David
>
>
>
>
> --
> 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/20110511/fbb94460/attachment.html>