updated docs

.gitignore

@@ -3,3 +3,5 @@
 bazel-*
 compile_commands.json
 user.bazelrc
+docs/_build/
+docs/xml/

Readme.md

@@ -34,3 +34,18 @@ A single producer, multiple consumer, fifo buffer.
 
 ### Callback
 Contains a general definition for callbacks, used at several places.
+
+## Documentation
+The documentation is available [here](https://embeddedutil.readthedocs.io).
+But you can also build it locally from sources.
+Install the following dependencies
+  * doxygen
+  * python 3.7
+  * sphinx
+  * breathe (a sphinx plugin)
+then issue
+```
+$ sphinx_build -T -b html docs docs/_build
+```
+from the project root.
+You can then find the produced html output in `docs/_build`

docs/Debug.rst

@@ -19,6 +19,59 @@ The listed function declarations
 have to be implemented by the
 user.
 
+How to use
+----------
+
+Use the library by listing the ``@EmbeddedUtilities//:Debug`` target
+in the ``deps`` attribute of your ``cc_*`` rule.
+
+Then include the header where needed::
+  
+  #include "Util/Debug.h"
+
+The header file provides the ``debug``
+macro. Writing::
+
+  debug(MyType, variable);
+
+will expand to::
+
+  printMyType(variable);
+
+Additionally the header lists ``printType(Type argument)`` function
+declarations for commonly used types. As stated above Debug is a 
+header only library. None of the function declarations ships
+with an implementation currently. You will have to implement
+every function yourself. There are plans to change this and
+implement efficient print functions.
+
+To enable the compiler to remove content of unneeded debug
+output you should write the statements like this::
+
+  debug(String, "My debug output");
+
+Do not use the debug function for Strings to print other things
+in a way like this::
+
+  char some_text[32] = {0};
+  sprintf(some_text, "My Message with int %i", some_int);
+  debug(String, some_text);
+
+Doing this will in most cases lead to the array and the
+format string ending up in your program memory.
+Instead do the following::
+
+  debug(String, "My Message with int ");
+  debug(UInt8, some_int);
+
+and implement both corresponding print functions.
+
+To enable debug output compile the corresponding ``*.c`` files
+with the ``-DDEBUG=1`` flag.
+To disable the output specify ``-DDEBUG=0`` instead.
+Not setting the debug flag at all will result in a warning.
+
+
 Util/Debug.h
 ------------