.. index:: contrib, git, patch, translation Contribute ********** OpenSVC projects, including this documentation, are hosted on Github. Install Git =========== :: sudo apt-get install git git config --global user.name "First Last Name" git config --global user.email "first.lastname@domain.com" Clone a Project =============== :: git clone https://github.com/opensvc/docs.opensvc.com.git git clone https://github.com/opensvc/opensvc.git Or fork on Github and clone from there. Send Patches ============ Submit a merge request through Github for projects hosted there. Contribute Documentations ========================= Getting Started --------------- Install the sphinx documentation generator and ansi2html software https://github.com/ralphbean/ansi2html For example, on a debian-based system: :: sudo apt-get install python-sphinx python-sphinx-rtd-theme Install ansi2html: :: sudo pip install ansi2html Clone the documentation project: :: git clone https://github.com/opensvc/docs.opensvc.com.git Step into the cloned project directory: :: cd docs.opensvc.com Modify the documentation source files (.rst located in the ``sources`` directory), and then use the Makefile to build the html documentations: :: make clean ; make osvc Once the build is done, all html files can be found in the ``docs.opensvc.com/build/html`` folder. Command Line Output Coloring ---------------------------- When producing command line output, it is expected to follow the steps below to preserve colors, so as to provide a better experience for futures readers: First generate raw html code from cli: :: $ om node print devs --color=yes | ansi2html -i Edit the .rst document and copy/paste the previous output in a ``.. raw:: html`` block, enclosed between ``
`` and ```` : :: .. raw:: html
centos71.opensvc.com Type Size Pct of Parent `- vda linear 15g - |- vda1 linear 500m 3% `- vda2 linear 14g 96% |- centos_centos71-swap linear 1g 10% `- centos_centos71-root linear 13g 89% |- loop2 linear 50m 0% | |- testsvc1-lv1 linear 20m 40% | `- testsvc1-lv2 linear 20m 40% |- loop1 linear 100m 0% | |- testsvc3-lv2 linear 20m 20% | |- testsvc3-lv1-real linear 52m 52% | | |- testsvc3-lv1 linear 52m 100% | | `- testsvc3-osvc_sync_lv1 linear 52m 100% | `- testsvc3-osvc_sync_lv1-cow linear 8m 8% | `- testsvc3-osvc_sync_lv1 linear 52m 650% `- loop0 linear 100m 0% |- testsvc2-lv1 linear 52m 52% `- testsvc2-lv2 linear 20m 20%After building html documentation, the result looks like: .. raw:: html
centos71.opensvc.com Type Size Pct of Parent `- vda linear 15g - |- vda1 linear 500m 3% `- vda2 linear 14g 96% |- centos_centos71-swap linear 1g 10% `- centos_centos71-root linear 13g 89% |- loop2 linear 50m 0% | |- testsvc1-lv1 linear 20m 40% | `- testsvc1-lv2 linear 20m 40% |- loop1 linear 100m 0% | |- testsvc3-lv2 linear 20m 20% | |- testsvc3-lv1-real linear 52m 52% | | |- testsvc3-lv1 linear 52m 100% | | `- testsvc3-osvc_sync_lv1 linear 52m 100% | `- testsvc3-osvc_sync_lv1-cow linear 8m 8% | `- testsvc3-osvc_sync_lv1 linear 52m 650% `- loop0 linear 100m 0% |- testsvc2-lv1 linear 52m 52% `- testsvc2-lv2 linear 20m 20%Decorating with sphinx roles ---------------------------- It is recommended to use the sphinx roles below to improve documentation rendering. As an example for a service, use the syntax:: :c-svc:`svc1` which will be rendered as :c-svc:`svc1` +---------------------------------------------------+-----------------------------------------------+ | Role Syntax | Rendering | +===================================================+===============================================+ | ``:c-action:`action``` | :c-action:`action` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-docker-repo:`repo``` | :c-docker-repo:`repo` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-docker-registry:`registry``` | :c-docker-registry:`registry` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-node:`node``` | :c-node:`node` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-svc:`svc``` | :c-svc:`svc` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-res:`res``` | :c-res:`res` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-tag:`tag``` | :c-tag:`tag` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-svc-env:`svc-env``` | :c-svc-env:`svc-env` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-env:`env``` | :c-env:`env` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-pkg:`pkg``` | :c-pkg:`pkg` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-net:`net``` | :c-net:`net` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-check:`check``` | :c-check:`check` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-form:`form``` | :c-form:`form` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-report:`report``` | :c-report:`report` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-metric:`metric``` | :c-metric:`metric` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-chart:`chart``` | :c-chart:`chart` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-group:`group``` | :c-group:`group` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-priv:`priv``` | :c-priv:`priv` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-user:`user``` | :c-user:`user` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-dns-domain:`domain.com``` | :c-dns-domain:`domain.com` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-dns-record:`example.com. IN A 12.13.14.15``` | :c-dns-record:`example.com. IN A 12.13.14.15` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-fset:`fset``` | :c-fset:`fset` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-disk:`disk``` | :c-disk:`disk` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-array:`array``` | :c-array:`array` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-diskgroup:`diskgroup``` | :c-diskgroup:`diskgroup` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-rule:`rule``` | :c-rule:`rule` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-rset:`ruleset``` | :c-rset:`ruleset` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-modset:`moduleset``` | :c-modset:`moduleset` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-mod:`module``` | :c-mod:`module` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-app:`application``` | :c-app:`application` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-close:`close``` | :c-close:`close` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-fullscreen:`fullscreen``` | :c-fullscreen:`fullscreen` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-shrink:`shrink``` | :c-shrink:`shrink` | +---------------------------------------------------+-----------------------------------------------+ | ``:c-link:`link``` | :c-link:`link` | +---------------------------------------------------+-----------------------------------------------+ | ``:kw:`keyword``` | :kw:`keyword` | +---------------------------------------------------+-----------------------------------------------+ | ``:cmd:`command``` | :cmd:`command` | +---------------------------------------------------+-----------------------------------------------+ | ``:opt:`opt``` | :opt:`opt` | +---------------------------------------------------+-----------------------------------------------+ .. seealso:: http://www.sphinx-doc.org/en/stable/contents.html `Sphinx Documentation