diff --git a/modules/base/doc/base.rst b/modules/base/doc/base.rst index 8bec08e983113dffdae61f80ef509ae6fecd9abe..6e0a6caf5f16b2367498e4284a98a1f067be92dd 100644 --- a/modules/base/doc/base.rst +++ b/modules/base/doc/base.rst @@ -1,9 +1,7 @@ -:mod:`ost.settings` - Locate Files and Retrieve Preferences +:mod:`ost` - OpenStructure Base Module ================================================================================ -.. automodule:: ost.settings - :synopsis: Helper Functions to Locate Files and Retrieve Preferences - :members: - - +.. toctree:: + logging + settings diff --git a/modules/base/doc/logging.rst b/modules/base/doc/logging.rst new file mode 100644 index 0000000000000000000000000000000000000000..726b60acbbc7f05e609cbafa9126546ab2025290 --- /dev/null +++ b/modules/base/doc/logging.rst @@ -0,0 +1,113 @@ +Logging +================================================================================ + +.. currentmodule:: ost + +How to log messages +-------------------------------------------------------------------------------- + +OpenStructure has an easy to use Logging API. Depended on how severe the message +is, one of the following four methods can be used to log the message: + + .. method:: LogError(message) + + Use this Method to log whenever an error occured that may cause the + application to fail + + .. method:: LogMessage(message) + + Use this Method to warn the user that something went wrong but generally does + not pose a threat to the stability of the application + + .. method:: LogVerbose(message) + + Use this Method to inform the user about processed data + + .. method:: LogDebug(message) + + Use this Method for informational messages that can help debug the program + + +Log sinks +-------------------------------------------------------------------------------- + +It is possible to log into different log backends namely log sinks. Log sink classes +define, how to handle log messages: + +.. class:: LogSink + + .. method:: LogMessage(message, severity) + + This method is called whenever something has been logged. This i a pure virtual + function therefore it must be overloaded in base classes. + + :param message: The logged message + + :type message: :class:`str` + + :param severity: Marks how severe the logged message is, starts from 0 which + is really important. Value is always 0 or larger + + :type severity: :data:`int` + +There are four LogSink implementations available in OpenStructure: + +.. class:: FileLogSink + + The FileLogSink logs all messages into the given file. + +.. class:: NullLogSink + + The NullLogSink suppresses all LogMessages + +.. class:: ObservedLogSink + + An observed LogSink allows to log into multiple sinks. + + .. method:: AttachObserver(sink) + + Attach an Observer which will be called whenever something has been logged + + .. method:: RemoveObserver(sink) + + Removes the given sink it will no longer be called when something has been logged + +The following snippet explains how to create a custom log sink which logs to the python shell: + +.. code-block:: python + + class PyLogger(ost.LogSink): + def __init__(self): + ost.LogSink.__init__(self) + + def LogMessage(self, message, severity): + print severity, message + + +To change the logger you can use the following methods: + + .. method:: PushLogSink(sink) + + Change the log sink to the given sink + + .. method:: PopLogSink() + + Change the log sink back to the previous sink + + +Verbosity Level +-------------------------------------------------------------------------------- + +You can set the verbosity level of the Logger with the following methods: + + .. method:: PushVerbosityLevel(verbosity): + + Change the Verbosity Level to the given integer value. All LoggedMethods which + have a severity above verbosity will not be passed to the current log sink. + + :type verbosity: :data:`int` + + .. method:: PopVerbosityLevel(): + + Change the log sink back to the previous verbosity level + \ No newline at end of file diff --git a/modules/base/doc/settings.rst b/modules/base/doc/settings.rst new file mode 100644 index 0000000000000000000000000000000000000000..8ba0ffc3786c1be74b85077fde007b696a85f50d --- /dev/null +++ b/modules/base/doc/settings.rst @@ -0,0 +1,6 @@ +:mod:`ost.settings` - Locate Files and Retrieve Preferences +================================================================================ + +.. automodule:: ost.settings + :synopsis: Helper Functions to Locate Files and Retrieve Preferences + :members: