Added documentation info

doc/buildsystem.rst

@@ -72,7 +72,6 @@ special targets:
 .. _cmake: http://www.cmake.org/
 .. _python: http://www.python.org/
 .. _boost: http://www.boost.org/
-.. _sphinx: http://sphinx-doc.org/
 
 ..  LocalWords:  cmake makefiles CMakeLists txt DOCTEST LINKCHECK conf html
 ..  LocalWords:  doctest linkcheck

doc/conf.py.in

@@ -260,6 +260,8 @@ rst_epilog = """
 .. |ost_s| replace:: OST
 .. |python| replace:: Python
 .. |sphinx| replace:: Sphinx
+.. _sphinx: http://sphinx-doc.org/
+.. |restructuredtext| replace:: reStructuredText
 .. |boost| replace:: Boost
 .. |git| replace:: Git
 """ % project

doc/contributing.rst

@@ -187,14 +187,29 @@ the Internet. Nevertheless, here is a short list of most important advices:
 * Test do not fail on purpose
 * No failing tests, that are considered 'this does not affect anything'
 
-.. documentation
-.. what is the docu system/ links to it
-.. where to put docu, how to write docu
-.. but: we are not here to write books
-.. consistency rule broken/ softened
-.. if sth needs highlighting, highlight it, if you emphasize like other bits of the code, nice, eg file names always go by :file:, but in the end, highlights are just there to fetch the readers attention, not really to bypass extra information. So do not spend to much time on developing the best formatting scheme in the world for variables, files, etc.
+--------------------------------------------------------------------------------
+Writing Documentation
+--------------------------------------------------------------------------------
+To create documentation, we use |sphinx|_ to go from |restructuredtext|_ files
+and API documentation in source files to HTML or man pages.
+
+For each module, at least one |restructuredtext| document exists, that gives an
+idea of concepts and pulls in interfaces from source. Copying files to the
+build directory, issuing the |sphinx| call and everything else that is needed
+to create the actual documentation is done by |cmake| and its makefiles. Hence,
+the :file:`CMakeLists.txt` of the :file:`doc` directory of a module is crucial.
+For documentation which does not relate to a particular module, the repository
+comes with a top-level :file:`doc` directory.
+
+While you should not spend to much time thinking about how to format
+documentation, here is a helpful list of standard formatters:
+http://sphinx-doc.org/markup/inline.html
 
+.. Extending Changelog
+   - is pulled into documentation automatically
 
+.. _restructuredtext: http://docutils.sf.net/rst.html
 
 ..  LocalWords:  cmake hotfix doctest linkcheck rebase BRANCHNAME rebasing py
-..  LocalWords:  CMakeLists txt rst pymod init submodule src
+..  LocalWords:  CMakeLists txt rst pymod init submodule src restructuredtext
+..  LocalWords:  makefiles formatters