README

Contributing to Documentation
*****************************

NorduGrid ARC6 documentation is mainly written in reStructuredText and
build with Sphinx to HTML pages, LaTeX (for printable PDF versions)
and ePub.

Recent source tree ("master" branch) build is available instantly via
Coderefinery GitLab Pages and deployed to the nordugrid.org on nightly
basis.

In particular the latest HTML version of this instructions can be
found online at:

   * GitLab CI build:
     http://nordugrid.pages.coderefinery.org/doc/dev
     elopers/documentation.html

   * NorduGrid web site:
     http://www.nordugrid.org/arc/arc6/developers/documentation.html

You can also download a tarball with all rendered HTML files to use
locally from this URL: https://source.coderefinery.org/nordugrid/doc/
-/jobs/artifacts/master/raw/sphinx-docs.tar.gz?job=build_docs


Commiting and reviewing changes
===============================

Contribution is possible by direct push to the repo, no need for merge
requests if you are fixing typos or other content that does not
requires review!

Note: In the renderend HTML version there is a link at the bottom of
  each page labeled *Edit page source on GitLab*. Using this link you
  can edit the page source in your web-browser without the need to
  checkout source tree

In case you want to add something new that requires the review
process:
   * create the new branch (in the same repository, no need to fork)

   * open a merge request to "master" branch

   * in-line and general discussion of the particular contribution
     is inside merge request.


Documentation structure
=======================

As reflected in the main index page, the documentation logically
divided into the following groups:

   * Documentation for Infrastructure Users

   * Documentation for Infrastructure Admins

   * Documentation for Developers

   * Technical Documents Describing ARC Components

Admins documentation is the most developed part for ARC6. We aimed to
have dedicated documents for each particular topic and then bound them
in the following way:

   * The introductory Try ARC6: towards distributed computing in a
     few minutes that contains a zero-configuration case hands-on
     instruction to help new users and admins getting started with ARC
     CE.

   * Main ARC Computing Element Installation and Configuration Guide
     that contains general installation and configuration flow for
     production *Computing Element* deployment. The guide itself
     should be brief enough and holds only main examples. All detailed
     instruction for each particular subsystem configuration should be
     written in the dedicated document that linked to this guide.

   * ARC Configuration Reference Document automatically rendered
     from text version in the code source tree. Targeted for web-
     search. The ultimate configuration options description we have.

   * All other dedicated documents goes to In-deps ARC CE
     Configuration and Tuning Guides section in case someone wants to
     access them directly instead of following installation guides
     links.


Source tree directory structure
===============================

Sources of documents in rST format are placed into the "source"
directory that contains the following structure:

   * "_static" - logo and CSS files [1]

   * "_templates" - Sphinx HTML theme layout tuning [1]

   * "_extensions" - Custom sphinx extensions developed for ARC [1]

   * "common" - directory used to store common for all ARC customers
     documentation, including admins, users and developes. This
     documents are hidden in the main TOC tree, instead they are
     linked from other various documents when needed.

        * "repos" - this directory holds repository configuration
          instructions for release, nightlies, etc. Main index page
          have repos pointers as well as Try ARC6 and Install Guide.

        * "changelog" - documents that describe changes between ARC
          versions.

   * "admins" - directory used to store Documentation for
     Infrastructure Admins. The main documents that represent the
     entry points to *ARC Computing Element* installation and
     configuration resides directly in this directory.

        * "details" - this subdirectory designed to hold detailed
          configuration instructions for ARC CE subsystems, like
          Working with RunTime Environments in ARC6 that describe all
          aspects of RTEs in-depth. This documents intentionally moved
          deeper in the main TOC tree to prevent first levels
          flooding. If you can find a chapter in main install guide
          that cat point to the in-depth document in question - this
          is a right place to store it.

        * "commands" - place for automatically generated command
          line option reference for ARC tools. At the time of writing
          the Python tools represented there.

        * "archery" - for the documents that not related to
          *Computing Element* another subdirectory should be created.
          At the time of writing only ARCHERY documentation of that
          kind is available.

   * "developers" - directory used to store Documentation for
     Developers. As long as we don’t have many of this kind of
     documents everything that contains implementation details (how
     stuff coded, which variable used, etc) should go there.

   * "tech" - directory used to store Technical Documents Describing
     ARC Components. Now it holds only index document that contains
     references to the available PDFs that is verified to be
     applicable to ARC6 release. To add more, use template inside the
     index file.

   * "users" - directory used to store Documentation for
     Infrastructure Users. If document is user-oriented - place it
     here.

   * "sdk" - place for Doxygen SDK documentation integration to
     Sphinx build [1]

   * "testing" - directory used to store the documents for ARC 6
     Testing Area.

   * "wip" - “work in progress” area hidden in the TOC tree. You can
     use it for incomplete documents that should not be publicly
     advertised yet, but still will be built and available via "/wip/"
     URL in produced HTML files.

[1] Do not touch unless you are modifying the Sphinx build itself.
    Nothing there affects documentation writting process.


Index files
-----------

Each directory in the source tree contains "index.rst" file that is
used to link other documents in the same TOC tree. Upper-level
"index.rst" file contains references to "index.rst" files in the
subdirectories, that in turns contains pointers to the other
documents.

Note: When you add a new document, add a reference to the
  "index.rst" in the same directory

Just follow the "index.rst" chain (look for "toctree" keyword)
starting from the "source" directory to get familiar with TOC linking
structure.


Storing images
--------------

When you need to add images to your document you should upload the
image file itself and refer to it from the ".rst".

ARC6 documentation structure implies that image files are stored
inside the "images" subdirectory in the document location. Then
referencing is done by relative path, e.g:

   .. figure:: images/shared_sessiondir_yes.svg


Building the docs
=================

The top directory in the source tree contains "build.sh" script that:

   * checkout the ARC source code tree and configures it with
     packaging-like paths

   * builds Doxygen SDK documentation

   * converts "arc.conf.reference" to rST

   * copies documentation parts from ARC source code tree (for
     developers section)

   * prepare automatically generated documentation for CLI commands

   * builds HTML

   * builds PDF (with LaTeX)

   * builds ePub

On commit the GitLab CI configured to automatically invoke the
"build.sh" to produce rendered documentation. Documentation archive is
avaiable as CI job artifacts and for "master" branch is deployed to
GitLab Pages.

To build the docs on your local machine you should have at least
Sphinx installed. Additionally you should be able to configure ARC
source tree and ARC Python command dependencies for auto-generated
parts.

Complete and up-to-date list of dependencies defined for CI build and
can be found in ".gitlab-ci.yml".

PDF builds with LaTeX is the most heavy part from the both time and
needed additional packages perspective. For HTML rendering local
debugging it is recommended to use the "html" script argument the
skips PDF and ePUB:

   [user@localhost doc]$ ./build.sh html

Point your browser to "file:///path/to/doc/build/html/index.html" to
view the HTML rendering locally.