From d5cea5037016b85d04f81fe2e6a33d5f84247834 Mon Sep 17 00:00:00 2001 From: Nicolas Sebrecht Date: Tue, 10 Mar 2015 03:56:58 +0100 Subject: [PATCH] doc: move all sources to the same directory Signed-off-by: Nicolas Sebrecht --- docs/CodingGuidelines.rst | 51 ------------------------------ docs/doc-src/CodingGuidelines.rst | 52 ++++++++++++++++++++++++++++++- 2 files changed, 51 insertions(+), 52 deletions(-) delete mode 100644 docs/CodingGuidelines.rst mode change 120000 => 100644 docs/doc-src/CodingGuidelines.rst diff --git a/docs/CodingGuidelines.rst b/docs/CodingGuidelines.rst deleted file mode 100644 index 92cc3be..0000000 --- a/docs/CodingGuidelines.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. -*- coding: utf-8 -*- -.. _OfflineIMAP: https://github.com/OfflineIMAP/offlineimap -.. _OLI_git_repo: git://github.com/OfflineIMAP/offlineimap.git - -================================= -Coding guidelines for OfflineIMAP -================================= - -.. contents:: -.. .. sectnum:: - -This document contains assorted guidelines for programmers that want -to hack OfflineIMAP. - - ------------------- -Exception handling ------------------- - -OfflineIMAP on many occasions re-raises various exceptions and often -changes exception type to `OfflineImapError`. This is not a problem -per se, but you must always remember that we need to preserve original -tracebacks. This is not hard if you follow these simple rules. - -For re-raising original exceptions, just use:: - - raise - -from inside your exception handling code. - -If you need to change exception type, or its argument, or whatever, -use this three-argument form:: - - raise YourExceptionClass(argum, ents), None, sys.exc_info()[2] - -In this form, you're creating an instance of new exception, so ``raise`` -will deduce its ``type`` and ``value`` parameters from the first argument, -thus the second expression passed to ``raise`` is always ``None``. -And the third one is the traceback object obtained from the thread-safe -``exc_info()`` function. - -In fact, if you hadn't already imported the whole ``sys`` module, it will -be better to import just ``exc_info()``:: - - from sys import exc_info - -and raise like this:: - - raise YourExceptionClass(argum, ents), None, exc_info()[2] - -since this is the historically-preferred style in the OfflineIMAP code. diff --git a/docs/doc-src/CodingGuidelines.rst b/docs/doc-src/CodingGuidelines.rst deleted file mode 120000 index 7117956..0000000 --- a/docs/doc-src/CodingGuidelines.rst +++ /dev/null @@ -1 +0,0 @@ -../CodingGuidelines.rst \ No newline at end of file diff --git a/docs/doc-src/CodingGuidelines.rst b/docs/doc-src/CodingGuidelines.rst new file mode 100644 index 0000000..92cc3be --- /dev/null +++ b/docs/doc-src/CodingGuidelines.rst @@ -0,0 +1,51 @@ +.. -*- coding: utf-8 -*- +.. _OfflineIMAP: https://github.com/OfflineIMAP/offlineimap +.. _OLI_git_repo: git://github.com/OfflineIMAP/offlineimap.git + +================================= +Coding guidelines for OfflineIMAP +================================= + +.. contents:: +.. .. sectnum:: + +This document contains assorted guidelines for programmers that want +to hack OfflineIMAP. + + +------------------ +Exception handling +------------------ + +OfflineIMAP on many occasions re-raises various exceptions and often +changes exception type to `OfflineImapError`. This is not a problem +per se, but you must always remember that we need to preserve original +tracebacks. This is not hard if you follow these simple rules. + +For re-raising original exceptions, just use:: + + raise + +from inside your exception handling code. + +If you need to change exception type, or its argument, or whatever, +use this three-argument form:: + + raise YourExceptionClass(argum, ents), None, sys.exc_info()[2] + +In this form, you're creating an instance of new exception, so ``raise`` +will deduce its ``type`` and ``value`` parameters from the first argument, +thus the second expression passed to ``raise`` is always ``None``. +And the third one is the traceback object obtained from the thread-safe +``exc_info()`` function. + +In fact, if you hadn't already imported the whole ``sys`` module, it will +be better to import just ``exc_info()``:: + + from sys import exc_info + +and raise like this:: + + raise YourExceptionClass(argum, ents), None, exc_info()[2] + +since this is the historically-preferred style in the OfflineIMAP code.