From d08f6d15c21a1517ee27d894a051f3199cda4d8c Mon Sep 17 00:00:00 2001 From: Wieland Hoffmann Date: Sun, 11 Jan 2015 18:15:16 +0100 Subject: [PATCH] addmessageheader: Add a note about the incorrect rendering of the docstring The note tells people to look at the source of the method, which spinx.ext.viewcode conveniently links right next to the methods signature. Signed-off-by: Wieland Hoffmann --- docs/doc-src/conf.py | 3 ++- offlineimap/folder/Base.py | 5 +++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/doc-src/conf.py b/docs/doc-src/conf.py index e961ab2..3f4bb6c 100644 --- a/docs/doc-src/conf.py +++ b/docs/doc-src/conf.py @@ -23,7 +23,8 @@ from offlineimap import __version__,__author__ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.viewcode'] autoclass_content = "both" # Add any paths that contain templates here, relative to this directory. diff --git a/offlineimap/folder/Base.py b/offlineimap/folder/Base.py index 7121231..55b2bfc 100644 --- a/offlineimap/folder/Base.py +++ b/offlineimap/folder/Base.py @@ -441,6 +441,11 @@ class BaseFolder(object): - headername: name of the header to add - headervalue: value of the header to add + .. note:: + + The following documentation will not get displayed correctly after being + processed by Sphinx. View the source of this method to read it. + This has to deal with strange corner cases where the header is missing or empty. Here are illustrations for all the cases, showing where the header gets inserted and what the end result