[Gt-eos] GCT 6 documentation

[Mátyás Selmeci]

Hi all,

I've been spending some time getting the GT documentation built and
in a usable state.  My starting point was
<https://github.com/gridcf/gct-documentation>, which contained most, but
not all, of the globus.org website.  (Notably missing were the API
docs.  I'm guessing those are autogenerated from the source.)

I've extracted the GT 6.0 documentation from that repo into its own
repo, which I am hosting via GitHub.  There were two main reasons for
this:

- Most of the globus.org website just plain doesn't apply to us.
- Most of the globus.org website is built using PHP, which GitHub
  hosting does not support.

My demo site is at <https://matyasselmeci.github.io/gct6-docs/>.  Please
take a look and submit comments.  The build process is manual; we can
automate it once we're satisfied with the results.  My demo site does
not include PDFs because they're large and binary but you can build them
yourselves (see below).

I went through the files and changed names where appropriate.  Let me
know if you find things I should change or things I shouldn't have
changed.

The results look different because I didn't use the Globus site's CSS
files. IMO it's a bad idea to make our site look like a carbon copy of
the original, but we can update the style later if people don't like it.


To build your own copy of the site (including the PDFs), do the
following:

1. Install the requirements.
   For HTML:
   - asciidoctor
   For PDF:
   - asciidoctor-pdf
   - ghostscript

2. Clone my GitHub repo <https://github.com/matyasselmeci/gct6-docs>.

3. Run `make clean` to get rid of the existing HTML files.

4. Run `make html` to make HTMLs, `make pdf` to make PDFs, or plain
   `make` to make both.  Expect a few warnings from AsciiDoctor; they
   should be harmless.

5. Open index.html in your favorite web browser.


Items we need to work on (roughly in priority order):

- Updating the installation documents, e.g. at
  <https://matyasselmeci.github.io/gct6-docs/admin/install/index.html#install-bininst>.
  We'll need to figure out how we're going to distribute binaries for
  various platforms before we can do that.

- Reviewing the rest of the docs for content, formatting,
  outdatedness, broken links, conversion warnings, etc.

- Adding API docs.

- Automating the build process.

- Improving the doc build process.  There are two known bugs:

  - `make` does not always update HTML pages when their sources are
    changed; this has to do with doc fragments being #included (or the
    AsciiDoc equivalent) into the main docs.  `make clean` before
    building (or `make -B`) works around that.

  - `asciidoctor-pdf` sometimes generates blank PDFs when it feels like
    it.  Deleting the PDFs and rerunning `make` often solves the
    problem.


Please take a look and send comments.  Once we're satisfied with the
general approach, I can move the repository to the gridcf organization.


Thanks,
-Mat
-- 
Mátyás (Mat) Selmeci
Open Science Grid Software Team / Center for High-Throughput Computing
University of Wisconsin-Madison Department of Computer Sciences


-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4181 bytes
Desc: S/MIME Cryptographic Signature
URL: <http://mailman.egi.eu/pipermail/gt-eos/attachments/20180302/4bbd237f/attachment.p7s>