[FEATURE] Rewrite documentation

DevLog has changed completely, so documentation needs to be
rewritten (and in reST format).

Change-Id: I9d340ce2a015dbf982cf4dfae98fb7e856cb76b5
Resolves: #78504
Releases: 3.0
Reviewed-on: https://review.typo3.org/50556
Reviewed-by: Francois Suter <[email protected]>
Tested-by: Francois Suter <[email protected]>

Author: Francois Suter

ChangeLog

@@ -1,3 +1,7 @@
+2016-11-09 Francois Suter <[email protected]>
+
+	* Rewrote documentation and moved it to reST, resolves #78504
+
 2016-11-01 Francois Suter <[email protected]>
 
 	* Updated and cleaned up the language files, resolves #78528

Documentation/.gitignore

@@ -0,0 +1,24 @@
+#########################
+# Git
+# global ignore file
+########################
+# ignoring temporary files (left by e.g. vim)
+# ignoring by common IDE's used directories/files
+# dont ignore .rej and .orig as we want to see/clean files after conflict resolution
+#
+# for local exclude patterns please edit .git/info/exclude
+#
+*~
+*.bak
+*.idea
+*.project
+*.swp
+.buildpath
+.cache
+.project
+.session
+.settings
+.TemporaryItems
+.webprj
+nbproject
+_make

Documentation/Developer/Index.rst

@@ -0,0 +1,145 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+.. _developer:
+
+Developer manual
+----------------
+
+
+.. _developer-logging-method:
+
+Using the logging method
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+To log something simply call :code:`\TYPO3\CMS\Core\Utility\GeneralUtility::devLog()`.
+This method takes the following parameters:
+
++-----------+-----------------------------------------------------------------------+
+| $msg      | The message that you want to write to the log                         |
++-----------+-----------------------------------------------------------------------+
+| $extKey   | The key of the extension writing to the log                           |
++-----------+-----------------------------------------------------------------------+
+| $severity | Indication of the severity of the message. The following values are   |
+|           | expected:                                                             |
+|           |                                                                       |
+|           | - -1 for ok status                                                    |
+|           | - 0 for a purely informational message                                |
+|           | - 1 for a notice                                                      |
+|           | - 2 for a warning                                                     |
+|           | - 3 for a (fatal) error                                               |
+|           |                                                                       |
+|           | This parameter is optional and defaults to 0.                         |
++-----------+-----------------------------------------------------------------------+
+| $dataVar  | This variable can be any type of data that you wish and that you find |
+|           | useful for information or debugging purposes. The Database Writer     |
+|           | serializes it before storage in the database.                         |
+|           |                                                                       |
+|           | This parameter is optional and defaults to false.                     |
++-----------+-----------------------------------------------------------------------+
+
+.. warning::
+
+   If you store a lot of stuff in the :code:`$dataVar` or
+   if you call the "devLog" very frequently, you may end up with a
+   very large "tx\_devlog\_domain\_model|_entry" table in your database.
+   Check it out regularly and don't hesitate to use the :ref:`clean up features <user-backend-module-clear-entries>`
+   as the relevant :ref:`configuration options <installation-configuration-database-writer>`.
+
+
+.. _developer-logging-method-severity-levels:
+
+More about severity levels
+""""""""""""""""""""""""""
+
+It may not always be easy to choose a severity level. The descriptions
+below go into a bit more detail and will – hopefully – make the choice
+easier.
+
+OK (-1)
+  These events indicate that everything went fine, no
+  error occurred (at least up to that point where the event was
+  created). No action needs to be taken.
+
+Info (0)
+  These events are purely informational. They are
+  normally used for debugging purposes only and require no special
+  action.
+
+Notice (1)
+  Abnormal condition, but not blocking. Notices are
+  meant to raise attention. Processes have been completed, but things
+  are not running as smoothly as they could and the condition should be
+  investigated.
+
+Warning (2)
+  These events are used to notify significant
+  problems. Processes have been completed, but parts of them may be
+  missing, wrong or corrupted. Warnings should not be ignored and action
+  should definitely be taken.
+
+Error (3)
+  These events signal that something went fatally wrong.
+  Processes were not completed and action is definitely needed.
+  Alternately this level may be used to point to a failed event, but in
+  a process where failure can be expected, e.g. a login attempt with the
+  wrong password.
+
+
+.. _developer-extra-information:
+
+Extra information
+^^^^^^^^^^^^^^^^^
+
+The devlog extension stores information beyond the parameters passed to the
+:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::devLog()` method. Some of it
+is automatically retrieved, like the id of the currently logged in BE user, if any.
+
+If the devlog call is made in the FE context, the page id will also automatically
+be retrieved from :code:`$GLOBALS['TSFE']->id. This variable is not defined in other contexts,
+in particular the BE. There is still a way to pass a page id to the devlog, if it makes sense,
+but you need to set it yourself in the global variable
+:code:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['GLOBAL']['debugData']['pid']`.
+If defined, this variable will be taken into account by the devlog.
+
+All this work happens in the :class:`\\Devlog\\Devlog\\Utility\\Logger` class.
+
+
+.. _developer-custom-writers:
+
+Custom Writers
+^^^^^^^^^^^^^^
+
+The data passed in the :code:`\TYPO3\CMS\Core\Utility\GeneralUtility::devLog()`
+call is stored by classed called "Writers". The extension provides two Writers
+out of the box: one write to the database, the other to a file. It is pretty
+easy to develop custom Writers.
+
+First you want to create a new class which extends
+:class:`\\Devlog\\Devlog\\Writer\\AbstractWriter`, which itself implements
+:class:`\\Devlog\\Devlog\\Writer\\WriterInterface`. The interface
+defines a single method called :code:`write()` which should take care of
+storing each log entry wherever and however it wants.
+
+Once you hace created your writer, register it in your extension's
+:file:`ext_localconf.php` file with the following syntax:
+
+.. code-block:: php
+
+	$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['devlog']['writers']['foobar'] = \Foo\Bar\Writer\FooBarWriter::class;
+
+
+where :code:`foobar` should be a unique key for your Writer.
+
+.. note::
+
+   It is actually possible to overwrite the default Writers be registrer a different
+   class for keys :code:`db` (Database Writer) and :code:`file` (File Writer).
+
+   It would also be possible to disable a Writer, by unsetting its entry in the
+   :code:`$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['devlog']['writers']` array.