Move documentation across multiple pages.

docs/conf.py

@@ -5,7 +5,7 @@
 source_suffix = '.rst'
 master_doc = 'index'
 
-project = u'Chevah Garden of Eden Creation Kit'
+project = u'C.G.E.C.K.'
 copyright = u'2017, Chevah Team'
 author = u'Chevah Team'
 
@@ -26,8 +26,10 @@
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ['_static']
+html_logo = '_static/chevah-logo.png'
 html_theme_options = {
+    'logo_only': True,
     'collapse_navigation': True,
     'display_version': False,
-    'navigation_depth': 2,
+    'navigation_depth': 3,
 }

docs/index.rst

@@ -1,9 +1,6 @@
 Chevah Garden of Eden Creation Kit
 ##################################
 
-.. image:: _static/chevah-logo.png
-   :align: center
-
 These pages describe the common knowledge we use to run the project.
 
 It can be considered the ultimate textbook for the project.
@@ -59,6 +56,7 @@ Please let us know if we fail to properly cite the source.
 
 .. toctree::
     :maxdepth: 2
+    :numbered:
 
     styleguide/index
     programming/index

docs/product/documentation.rst

@@ -71,6 +71,9 @@ semicolons, rather than after the Nth column.
 Structure of the Documentation
 ==============================
 
+The sections of the documentation should be numbered, in this way the provide
+a more precise way of referencing a certain part of the documentation.
+
 
 Introduction
 ------------
@@ -472,134 +475,6 @@ Use the following convention:
 ``>`` means a client-shell command.
 
 
-Documenting the code
-====================
-
-Code documentation can be in the form of docstrings, comments, examples or
-tests.
-
-Use docstrings to document packages, modules, classes and functions regardless
-of what language it is - Python, shell, C etc.
-
-* Well documented code is extremely important.
-  Take time to describe components, how they work, their limitations, and the
-  way they are constructed.
-  Don't leave others in the team guessing what is the purpose of uncommon or
-  non-obvious code.
-
-**Python Examples:**
-
-Document code as part of docstrings and not as comments.
-
-.. sourcecode:: python
-
-    def iamanExample(doc):
-        """
-        A simple docstring is placed here.
-        """
-          config = self.createSomethingHere('')
-
-Other tips about Python docstrings are this
-`wiki entry <https://en.wikipedia.org/wiki/Docstring>`_.
-
-**Shell Examples:**
-
-Use comments to document what the shell script does and notes to keep in mind
-to the developers using a script.
-
-.. sourcecode:: shell
-
-    #
-    # This script is used to check all combination for cryto algorithms between
-    # twisted.conch.ssh server and OpenSSH client.
-    #
-    KEXs='diffie-hellman-group14-sha1 diffie-hellman-group1-sha1
-    diffie-hellman-group-exchange-sha1 diffie-hellman-group-exchange-sha256'
-    MACs='hmac-sha2-512 hmac-sha2-256 hmac-sha1 hmac-md5'
-
-Document how portions of the script works, where needed:
-
-.. sourcecode:: shell
-
-    # Put default values and create them as global variables.
-    OS='not-detected-yet'
-    ARCH='x86'
-
-**C Examples:**
-
-Use comments to document notes to the developer utilizing the c script.
-
-.. sourcecode:: c
-
-    /* file1() replacement (from file2, if you must know) */
-
-    #include "newfile.h"
-
-Use comments to provide further notes of additional changes / additions,
-where needed:
-
-.. sourcecode:: c
-
-    # This is the default-included GNU make and its counterpart: makeinfo.
-    export MAKE=/usr/sfw/bin/gmake
-    export MAKEINFO=/usr/sfw/bin/makeinfo
-
-
-Test code docstrings
---------------------
-
-Test code docstrings can contain information during the review process of new
-tests that can be written.
-
-.. sourcecode:: python
-
-    class TestHelpers(IAmATestCase):
-        """
-        The docstring here may add tests for helpers for a certain module
-        """
-        def test_of_a_module_1(self):
-         """
-         What is expected to happen in the first module of this test case
-         """
-        def test_of_a_module_2(self):
-         """
-         What is expected to happen in the second module of this first case
-         """
-
-.. sourcecode:: python
-
-    class MyClass(object):
-        """The class's docstring"""
-
-        def my_method(self):
-            """The method's docstring"""
-
-    def my_function():
-        """The function's docstring"""
-
-
-Production code docstrings
---------------------------
-
-Docstring are added in the production code to provide further information for
-readers and reviewers.
-
-For example:
-
-.. sourcecode:: python
-
-    def getSomethingNewHere(self):
-
-In this case, a docstring should be added to add further information:
-
-.. sourcecode:: python
-
-    def getSomethingNewHere(self):
-        """
-        A docstring describing what SomethingNewHere is about
-        """
-
-
 Marketing / Promotional Materials
 =================================
 

docs/programming/documentation.rst

@@ -0,0 +1,126 @@
+Documenting the code
+####################
+
+Code documentation can be in the form of docstrings, comments, examples or
+tests.
+
+Use docstrings to document packages, modules, classes and functions regardless
+of what language it is - Python, shell, C etc.
+
+* Well documented code is extremely important.
+  Take time to describe components, how they work, their limitations, and the
+  way they are constructed.
+  Don't leave others in the team guessing what is the purpose of uncommon or
+  non-obvious code.
+
+**Python Examples:**
+
+Document code as part of docstrings and not as comments.
+
+.. sourcecode:: python
+
+    def iamanExample(doc):
+        """
+        A simple docstring is placed here.
+        """
+          config = self.createSomethingHere('')
+
+Other tips about Python docstrings are this
+`wiki entry <https://en.wikipedia.org/wiki/Docstring>`_.
+
+**Shell Examples:**
+
+Use comments to document what the shell script does and notes to keep in mind
+to the developers using a script.
+
+.. sourcecode:: shell
+
+    #
+    # This script is used to check all combination for cryto algorithms between
+    # twisted.conch.ssh server and OpenSSH client.
+    #
+    KEXs='diffie-hellman-group14-sha1 diffie-hellman-group1-sha1
+    diffie-hellman-group-exchange-sha1 diffie-hellman-group-exchange-sha256'
+    MACs='hmac-sha2-512 hmac-sha2-256 hmac-sha1 hmac-md5'
+
+Document how portions of the script works, where needed:
+
+.. sourcecode:: shell
+
+    # Put default values and create them as global variables.
+    OS='not-detected-yet'
+    ARCH='x86'
+
+**C Examples:**
+
+Use comments to document notes to the developer utilizing the c script.
+
+.. sourcecode:: c
+
+    /* file1() replacement (from file2, if you must know) */
+
+    #include "newfile.h"
+
+Use comments to provide further notes of additional changes / additions,
+where needed:
+
+.. sourcecode:: c
+
+    # This is the default-included GNU make and its counterpart: makeinfo.
+    export MAKE=/usr/sfw/bin/gmake
+    export MAKEINFO=/usr/sfw/bin/makeinfo
+
+
+Test code docstrings
+====================
+
+Test code docstrings can contain information during the review process of new
+tests that can be written.
+
+.. sourcecode:: python
+
+    class TestHelpers(IAmATestCase):
+        """
+        The docstring here may add tests for helpers for a certain module
+        """
+        def test_of_a_module_1(self):
+         """
+         What is expected to happen in the first module of this test case
+         """
+        def test_of_a_module_2(self):
+         """
+         What is expected to happen in the second module of this first case
+         """
+
+.. sourcecode:: python
+
+    class MyClass(object):
+        """The class's docstring"""
+
+        def my_method(self):
+            """The method's docstring"""
+
+    def my_function():
+        """The function's docstring"""
+
+
+Production code docstrings
+==========================
+
+Docstring are added in the production code to provide further information for
+readers and reviewers.
+
+For example:
+
+.. sourcecode:: python
+
+    def getSomethingNewHere(self):
+
+In this case, a docstring should be added to add further information:
+
+.. sourcecode:: python
+
+    def getSomethingNewHere(self):
+        """
+        A docstring describing what SomethingNewHere is about
+        """

docs/programming/index.rst

@@ -14,5 +14,6 @@ requirements.
     generic
     review
     testing
+    documentation
     defects-tech-debt
     dependencies

docs/programming/testing.rst

@@ -78,6 +78,39 @@ Passing software to another developer without tests is like saying
 'Good luck dude!' - but instead we should say 'I've got you covered!'.
 
 
+Test Data
+=========
+
+When using data for the test, make sure that all the data is part of the
+same versioning system as the test code.
+
+1. In the best case, all test data should be generated by the test.
+
+2. If for various reason you have pre-generated data,
+   try to keep it in the same file and as close as possible to the test itself.
+
+   For example, keep the content of the file as string, and if the test really
+   need to read that content from a file or data, write it before the test,
+   run the test and the remove the file / database entry.
+
+3. If keeping it in the same as the test code is not possible, as a third best
+   keep it in a file which is versioned with the test code itself.
+
+In some exceptional cases (chicken and egg problems) there is no option to
+generate the data at test time or to keep in the same versioning system as
+the test code.
+For example when you want to run and end to end test to check that you can
+read and write a document from a database, you will have to start with testing
+the read operation against an existing data.
+
+In this case make sure that all pre-generated data is versioned using a well
+defined convention and that the pre-generated data is never modified or
+removed.
+In this way you can still run older versions of the code.
+Pre-generated data include pre-generated access to the outside resource
+(username / password / server address / port)
+
+
 Types of tests
 ==============
 

docs/styleguide/generic.rst

@@ -31,16 +31,21 @@ something is wrong.
 
 * Don't use abbreviation.
   Use full, meaningful names.
+  People with a C background might say that is always OK to use i and j for
+  the iterating, but most of our code is Python so write iterators so that
+  using an index is not needed.
 
 * Don't use tabs for indentation, and in general don't use tabs for anything
   else.
   The only exceptions are Makefiles.
 
 * Favour indentation using 4 spaces.
-  For deep nested languages (HTML, JS) it is OK to use 2 spaces.
+  For deep nested languages (HTML, XML) it is OK to use 2 spaces.
 
-* Maximum line length for code is 80 characters, but for Python we use 79 to be in
-  sync with PEP8 Style Guide for Python Code.
+* Maximum line length for code is 80 characters,
+  but for Python we use 79 to be in sync with PEP8 Style Guide for Python Code.
+  In this way, is easier to compare code, even when using a single monitor on
+  a laptop.
 
 * No need for the ultimate purism, when using / calling code from external
   libraries it is OK if those calls don't comply with coding convention.
@@ -122,9 +127,15 @@ Comments
 ========
 
 * All comments should be valid sentences and should end with a full stop (.).
+  In this way it is easier to see if the information is complete, or that
+  someone forget to complete a sentence.
 
 * Try to write code so that it speaks for itself, and so that a comment is not
   required.
+  Comments and code have a bad habit of getting out of sync and this will lead
+  to the confusion as you might not know whether the comment or the code is
+  expected behaviour.
+  To mitigate this, we have test, which have special docstrings.
 
 * Try to name variables, methods, functions so that they communicate their
   intent.