Commit f1c9e7eb authored by Andrii Salnikov's avatar Andrii Salnikov

documenting reST syntax (incomplete)

parent 732330a5
Pipeline #4353 passed with stages
in 16 minutes and 14 seconds
TODO: add main contributing part in plain text here
TODO: add reference to the HTML full doc
......@@ -19,9 +19,6 @@ 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
......
......@@ -4,15 +4,23 @@ 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.
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!
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 :doc:`main index <index>` page, the documentation logically divided into the following groups:
As reflected in the :doc:`main index </index>` page, the documentation logically divided into the following groups:
* :ref:`users_docs`
* :ref:`admins_docs`
......@@ -95,18 +103,105 @@ PDF builds with LaTeX is the most heavy part from the both time and needed addit
Point your browser to ``file:///path/to/doc/build/html/index.html`` to view the HTML rendering locally.
Writing Documentation in reStructuredText
=========================================
reStructuredText (reST) is the default plaintext markup language used by Sphinx. There is possible to render other markups but for consistency and better cross-referencing NorduGrid ARC6 documentation written solely in reStructuredText.
General Syntax
**************
reStructuredText markup specification is well documented in the several sources and was designed to be a simple and readable in plain-text.
Common text editors (including ``vim`` and ``emacs``) recognize reST markup and provide syntax highlighting out of the box.
Start with `reStructuredText Primer <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ on Sphinx docs.
Complete reST Markup Syntax can be found on `Docutils <http://docutils.sourceforge.net/rst.html>`_ starting with `Quick reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ document.
Sphinx also uses interpreted text roles to insert semantic markup (cross-referencing, etc) into docuemnts. To get familiar read `this document <http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_.
Just study the markup following the documentation and readinig the already written documents just here.
Code snippets
*************
There are different options for representing the code, starting with the simple literal blocks identified with ``::``.
It is advised to use ``code-block::`` directive to enable syntax highlighted rendering:
.. code-block:: rst
.. code-block:: ini
[gridftpd/jobs]
allowaccess = staticdn dnfromfile
In this example, the ``ini`` tag represents the syntax highlighting lexer identfier for Pygments. Look for `available lexers <http://pygments.org/docs/lexers/>`_ to serve your needs. The most common for our docs are: ``console``, ``bash``, ``ini`` and ``cfg``.
References
**********
Referencing another parts of documentation is necessary to achive usability. The typical referencing cases are:
Using custom label
------------------
Create label just above any of the paragraph headers with. The following markup creates ``my_label`` label.
.. code-block:: rst
.. _my_label:
My Heading
==========
Refering to a lable is possible from any other doument with:
.. code-block:: rst
read the :ref:`my_label`
In this case paragraph heading will be used for hyperlink text. If you want some custom text for hyperlink text use the following syntax:
.. code-block:: rst
read this :ref:`text <my_label>`
Refering arc.conf.reference
---------------------------
Autogenerater reST rendering of ``arc.conf.reference`` already contains labels for all configuration options and blocks that can be used.
The label name has the following structure:
* ``reference_<block name>[_<sub_block>...]_<option name>`` represents configration option inside block
* ``reference_<block name>[_<sub_block>...]`` represents block itself
For example:
.. code-block:: rst
In the ``arc.conf`` there is a dedicated :ref:`[lrms] <reference_lrms>` block that defines the type of your LRMS.
*Job session directory* is configured with :ref:`reference_arex_sessiondir` configurration option.
Referencing docs
----------------
Referencing the the whole document is similar to using labels, but instead of label name the document name (filename without extension) is used with ``:doc:`` keyword.
Example 1: Refer to the ``try_arc6.rst`` in the same source tree directory (relative path). Use the document header as hyperlink text:
.. code-block:: rst
:doc:`try_arc6`
Example 2: Refer to the ``repository.rst`` by absolute path (starting from sources top directory). Use the custom hyperlink text:
.. code-block:: rst
:doc:`NorduGrid Repositories </repos/repository>`
Adding notes
************
......@@ -116,3 +211,6 @@ Adding images
Graphviz
********
Converting from other sources
*****************************
......@@ -7,4 +7,5 @@ Implemantation Details for Developers
packages-services-naming.rst
configparser.rst
lrms.rst
documentation.rst
......@@ -56,7 +56,7 @@ for architecture internals (how parts of ARC was designed) you can follows this
.. _developers_docs:
Documentation for Developers
============================
****************************
If you are looking for development internal details of ARC (like how some stuff was coded) this part of
documentation is for you. Mainly for those who want to contribute to the project development,
......
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