[Gt-eos] GCT 6 documentation

[Mischa Salle]

Hi Mátyás,

it looks nice, great work!
A few small remarks:
- I think I'd probably wouldn't want the original globus CSS since it
  would only be confusing. Perhaps some small tweaks such as a slight
  broadening of the used part of the screen or perhaps a slightly
  smaller font.
- we should have our 'own' version of the Release Notes, since
  it now quite a few globus-links, including links to the Globus jira
  etc.
- not entirely sure, but I think jGlobus is pretty much dead.
- although we should host the API docs, I would keep them separate from
  this documentation since as you said they are produced from the source
  repo, not from the documentation repo.

  Best wishes,
  Mischa

On Fri, Mar 02, 2018 at 01:53:32PM -0600, Mátyás Selmeci wrote:
> 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
> 
> 



> _______________________________________________
> Gt-eos mailing list
> Gt-eos at mailman.egi.eu
> http://mailman.egi.eu/mailman/listinfo/gt-eos


-- 
Nikhef                      Room  H155
Science Park 105            Tel.  +31-20-592 5102
1098 XG Amsterdam           Fax   +31-20-592 5155
The Netherlands             Email msalle at nikhef.nl
  __ .. ... _._. .... ._  ... ._ ._.. ._.. .._..
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 3402 bytes
Desc: not available
URL: <http://mailman.egi.eu/pipermail/gt-eos/attachments/20180305/71d9eb83/attachment.p7s>