Commit 9ce005bd authored by Andrii Salnikov's avatar Andrii Salnikov

README with contribution instructions

parent e8749222
Pipeline #4280 passed with stage
in 16 minutes and 26 seconds
build/
source/README.rst
source/developers/configparser.rst
source/developers/lrms.rst
source/admins/reference.rst
......
=============================
Contributing to Documentation
=============================
NorduGrid ARC6 documentation is mainly written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ and build with `Sphinx <http://www.sphinx-doc.org/en/master/>`_ to HTML pages, LaTeX (for printable PDF versions) and ePub.
Contribution is possible by direct push to the repo, no need for merge requests!
Recent source tree CI ``master`` build is available instantly via `GitLab Pages <http://nordugrid.pages.coderefinery.org/doc/>`_ and deployed to the `nordugrid.org <http://www.nordugrid.org/documents/arc6/>`_ on nightly basis.
Documentation structure
=======================
As reflected in the :doc:`main index <index>` page, the documentation logically divided into the following groups:
* :ref:`users_docs`
* :ref:`admins_docs`
* :ref:`developers_docs`
* :ref:`tech_docs`
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 :doc:`/admins/try_arc6` that contains a zero-configuration case hands-on instruction to help new users and admins getting started with ARC CE.
* Main :doc:`/admins/arc6_install_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.
* :doc:`/admins/reference` 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 :doc:`/admins/details/index` 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 [#f1]_
* ``_templates`` - Sphinx HTML theme layout tuning [#f1]_
* ``admins`` - directory used to store :ref:`admins_docs`. 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 :doc:`/admins/details/rtes` 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 :doc:`install guide </admins/arc6_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 :ref:`developers_docs`. 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.
* ``repos`` - this directory holds repository configuration instructions that needed for users as well as admins and developers. This documents are hidden in the main TOC tree, instead they are linked from other various documents when needed. Main index page have repos pointers as well as :doc:`Try ARC6 </admins/try_arc6>` and :doc:`Install Guide </admins/arc6_install_guide>`
* ``sdk`` - place for Doxygen SDK documentation integration to Sphinx build [#f1]_
* ``tech`` - directory used to store :ref:`tech_docs`. 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 :ref:`users_docs`. If document is user-oriented - place it here.
* ``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.
.. [#f1] 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`` document using ``image::`` or ``figure::`` keywords.
To be consistent image files are stored inside the ``images`` subdirectory in the document location. Then referencing is done by relative path, e.g:
.. code-block:: rst
.. 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 :ref:`developers <developers_docs>` 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 <http://nordugrid.pages.coderefinery.org/doc/>`_.
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:
.. code-block:: console
[user@localhost doc]$ ./build.sh html
Point your browser to ``file:///path/to/doc/build/html/index.html`` to view the HTML rendering locally.
Writing Documentation in reStructuredText
=========================================
General Syntax
**************
Code snippets
*************
References
**********
Adding notes
************
Adding images
*************
Graphviz
********
This repository is intended to be the initial workplace for ARC6 documentation.
Some (major) reorganization may take place as ARC6 release date is approached.
Contribution is possibly by direct push, no need for merge requests!
Recent version of built source tree is avaiable here: http://nordugrid.pages.coderefinery.org/doc/
......@@ -19,6 +19,9 @@ fi
make -C src/doxygen SDK PYTHON=/usr/bin/python
cd $DOCROOT
# copy README
cp README.rst source/
export PYTHONPATH="$CODE_DIR/src/utils/python"
# generate reference.rst
......
.. _arc6_install_guide:
ARC6 Installation Guide
#######################
##########################################################
ARC Computing Element Installation and Configuration Guide
##########################################################
PREREQUISITES
*************
......
......@@ -7,14 +7,16 @@ enabling e-Science computing infrastructures with emphasis on processing of larg
ARC is being used to enable national and international e-infrastructures since its first release in 2002.
ARC is avaiable for variaty of GNU/Linux flavors via stable :doc:`Repositores <repos/repository>` or :doc:`Nigtly Builds <repos/nightlies-repo>` if you want to test the latest development release.
ARC is available for variety of GNU/Linux flavors via stable :doc:`Repositores <repos/repository>` or :doc:`Nigtly Builds <repos/nightlies-repo>` if you want to test the latest development release.
If you are new to ARC get started with the :doc:`Try ARC6 <admins/try_arc6>` quickstart guide to get an overview of main operations in the simple test case.
For production *Computing Element* deployment follow the :doc:`Installation and Configuration Guide <admins/arc6_install_guide>` that containst the structure and pointers to precise configuration of every ARC subsystem.
For production *Computing Element* deployment follow the :doc:`Installation and Configuration Guide <admins/arc6_install_guide>` that contains the structure and pointers to precise configuration of every ARC subsystem.
The ultimate description of each configuration option can be found in the :doc:`admins/reference`.
.. _users_docs:
Documentation for Infrastructure Users
**************************************
......@@ -25,6 +27,8 @@ This part of the documentation targeted to distributed computing infrastructure
users/index.rst
.. _admins_docs:
Documentation for Infrastructure Admins and Operators
*****************************************************
......@@ -36,6 +40,8 @@ If you are looking for ARC Computing Element setup instruction or performance tu
admins/index.rst
.. _tech_docs:
Technical Documents Describing ARC Components
*********************************************
......@@ -47,6 +53,8 @@ for architecture internals (how parts of ARC was designed) you can follows this
tech/index.rst
.. _developers_docs:
Documentation for Developers
============================
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment