Commit 8f4244ef authored by Andrii Salnikov's avatar Andrii Salnikov

contributing to docs rst overview finished

parent 4c7fdf5e
Pipeline #4854 passed with stages
in 3 minutes and 53 seconds
......@@ -10,7 +10,10 @@ Recent source tree CI ``master`` build is available instantly via `GitLab Pages
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!
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)
......@@ -64,12 +67,14 @@ Each directory in the source tree contains ``index.rst`` file that is used to li
Just follow the ``index.rst`` chain (look for ``toctree`` keyword) starting from the ``source`` directory to get familiar with TOC linking structure.
.. _storing_images:
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.
When you need to add images to your document you should upload the image file itself and refer to it from the ``.rst``.
To be consistent image files are stored inside the ``images`` subdirectory in the document location. Then referencing is done by relative path, e.g:
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:
.. code-block:: rst
......@@ -205,12 +210,53 @@ Example 2: Refer to the ``repository.rst`` by absolute path (starting from sour
Adding notes
************
To highlight statement visually use notes and warnings:
.. code-block:: rst
.. note::
Zero configured A-REX comes with EMI-ES and REST interfaces enabled.
.. warning::
This information is valid for releases of ARC 6 starting from 6.0.
Adding images
*************
In the ARC6 documentation images should be included with the caption.
It is accomplished with the `figure <http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure>`_ keyword.
After :ref:`storing image <storing_images>` inside ``images`` subdirectory, include it in reST document as:
.. code-block:: rst
.. figure:: images/shared_sessiondir_yes.svg
:align: center
:alt: Sessiondir is shared between ARC CE and WNs
Sessiondir is shared between ARC CE and WNs. No local scratchdir defined.
Sphinx build had been configured with image format autocoversion feature. So you can use any image format, including vector graphics.
Graphviz
********
If you want to illustrate some process or structure that can be shown as graph, consider using built-in `Graphviz <https://www.graphviz.org/>`_ functionality.
Simple usage examples can be found in ``admins/details/rtes.rst`` document within ARC documentation. Give it a try, it is easy.
Converting from other sources
*****************************
Converting the old documentation parts from LaTeX or Mediawiki markdown to reST is not a magical process that do everything automatically unfortunalely.
However you can get a good start with a `pandoc <https://pandoc.org/>`_ tool that do the conversion.
E.g. to convert LaTeX source simply run:
.. code-block:: console
[user ~]$ pandoc -f latex -t rst acix.tex > acix.rst
The ammount of efforts to edit the resulted ``.rst`` file and fix formatting issues is completely depends on the source itself (e.g. how the console ouput was formatted in the origin document). Images and references in most cases should be fixed separately after the pandoc.
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