From 842fbfa1e8ac9a88b97efbcf6020a98a103af1d0 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Tue, 22 Oct 2019 14:52:48 +0200 Subject: [PATCH 1/2] Warn about dangers of inheriting nodes in conf.py Closes #6751 --- doc/development/tutorials/todo.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/doc/development/tutorials/todo.rst b/doc/development/tutorials/todo.rst index f4ac85ac9..fa97c580b 100644 --- a/doc/development/tutorials/todo.rst +++ b/doc/development/tutorials/todo.rst @@ -107,6 +107,20 @@ is just a "general" node. `__ and :ref:`Sphinx `. +.. DANGER:: + + It is important to know that while you can extend Sphinx without + leaving your ``conf.py``, if you declare an inherited node right + there, you'll hit an unobvious :py:class:`PickleError`. So if + something goes wrong, please make sure that you put inherited nodes + into a separate Python module. + + For more details, see: + + - https://github.com/sphinx-doc/sphinx/issues/6751 + - https://github.com/sphinx-doc/sphinx/issues/1493 + - https://github.com/sphinx-doc/sphinx/issues/1424 + .. rubric:: The directive classes A directive class is a class deriving usually from From aafaa922378157a12eec988350c1b97561f8483f Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Mon, 13 Jan 2020 14:51:04 +0900 Subject: [PATCH 2/2] doc: Use attention for notes about nodes in conf.py --- doc/development/tutorials/todo.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/tutorials/todo.rst b/doc/development/tutorials/todo.rst index fa97c580b..e27528b5a 100644 --- a/doc/development/tutorials/todo.rst +++ b/doc/development/tutorials/todo.rst @@ -107,7 +107,7 @@ is just a "general" node. `__ and :ref:`Sphinx `. -.. DANGER:: +.. attention:: It is important to know that while you can extend Sphinx without leaving your ``conf.py``, if you declare an inherited node right