Improved documentation page for developers.

Moved some content from website to autogenerated documentation to prevent from repeating the same content on multiple places. Added information about versioning and tagging. (Redmine issue: #3361)

doc/sphinx/_doclib/development.rst

@@ -37,7 +37,49 @@ General guidelines
 * Reuse existing (even soft) dependencies. There is no need to use three competing IP address libraries. However, do not prevent application developer to use different one in his app, should he need to.
 
 
-Development cheat scheet
+Versioning
+--------------------------------------------------------------------------------
+
+This project uses the `semantic versioning <https://semver.org/>`__. When the
+**production** level packages are being built and deployed, the automated build
+system takes the project version directly from following files (paths are relative
+to project root):
+
+* ``lib/mentat/__init__.py``
+* ``package.json``
+
+Sadly you have to adjust the version string on both of these places, currently
+there is no way how to do it on one.
+
+When building the **release** or **development** level packages, the automated
+build system appends an internal build number as additional subversion. This way
+each build produces unique version string and unique package. This feature can
+be used during development to reduce the need for incrementing the version numbers
+manually between each builds.
+
+
+Tagging
+--------------------------------------------------------------------------------
+
+Each major and minor version release must be tagged within the repository. Please
+use only annotated or signed tags and provide short comment for the release. Before
+tagging please view existing tags so that you can attempt to maintain the style of
+the tag messages.
+
+.. code-block:: shell
+
+	# List all existing tags
+	git tag -l -n999
+
+	# Create new annotated tag and provide message
+	git tag -a v2.0.0
+
+	# Push tags to remote servers (if you are permitted to do so)
+	git push origin v2.0.0
+	git push buildbot v2.0.0
+
+
+Development essentials
 --------------------------------------------------------------------------------
 
 There is a project master *Makefile* in the root of the project repository which
@@ -71,7 +113,11 @@ would not be able to find required libraries. You may fix that by providing corr
 value to PYTHONPATH environment variable.
 
 Make sure, that the `pyflakes <https://pypi.org/project/pyflakes/>`__ library is
-already installed on your system.
+already installed on your system. You may install it by executing following command:
+
+.. code-block:: shell
+
+	pip3 install pyflakes
 
 
 Checking code with Pylint
@@ -96,7 +142,11 @@ would not be able to find required libraries. You may fix that by providing corr
 value to PYTHONPATH environment variable.
 
 Make sure, that the `pylint <https://pypi.org/project/pylint/>`__ library is already
-installed on your system.
+installed on your system. You may install it by executing following command:
+
+.. code-block:: shell
+
+	pip3 install pylint
 
 
 Running unit tests
@@ -110,13 +160,29 @@ command:
 	make test
 
 Make sure, that the `nose <https://pypi.org/project/nose/>`__ library is already
-installed on your system.
+installed on your system. You may install it by executing following command:
+
+.. code-block:: shell
+
+	pip3 install nose
 
 
-Generating documentation locally
+Documentation
 ````````````````````````````````````````````````````````````````````````````````
 
-You may generate the documentation locally by executing the following command:
+Project documentation is generated using the `Sphinx-doc <http://www.sphinx-doc.org/en/stable/contents.html>`__
+tool into various formats. Please use `RST <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
+markup features where appropriate to increase readability and cross-reference to
+related content. It should however still be possible to view the documentation of
+all Python modules in *Pythonic* way via `pydoc3 <https://docs.python.org/3/library/pydoc.html>`__
+and the result should still be more or less readable. Please test it immediately with:
+
+.. code-block:: shell
+
+	pydoc3 ./path/to/module.py
+
+You may generate and review the documentation locally by executing the following
+command:
 
 .. code-block:: shell
 
@@ -124,7 +190,30 @@ You may generate the documentation locally by executing the following command:
 
 Make sure, that the `Sphinx <https://pypi.org/project/sphinx/>`__ and
 `sphinx-rtd-theme <https://pypi.org/project/sphinx-rtd-theme/>`__ libraries are
-already installed on your system.
+already installed on your system. You may install them by executing following
+commands:
+
+.. code-block:: shell
+
+	pip3 install sphinx
+	pip3 install sphinx_rtd_theme
+
+Documentation will be generated into ``doc/sphinx/_build/html/manual.html``.
+
+
+Important resources
+````````````````````````````````````````````````````````````````````````````````
+
+* `pyflakes <https://github.com/PyCQA/pyflakes>`__
+* `pylint <https://pylint.readthedocs.io/en/latest/>`__
+* `nosetests <http://nose.readthedocs.io/en/latest/>`__
+* `pydoc3 <https://docs.python.org/3/library/pydoc.html>`__
+* `Sphinx-doc <http://www.sphinx-doc.org/en/stable/contents.html>`__
+
+  * `reStructuredText Primer <http://www.sphinx-doc.org/en/stable/rest.html>`__
+  * `Sphinx markup constructs <http://www.sphinx-doc.org/en/stable/markup/index.html>`__
+  * `The Python domain <http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain>`__
+  * `Documenting functions and methods <http://www.sphinx-doc.org/en/stable/domains.html#info-field-lists>`__
 
 
 Examples