From 77c5aaaa973dfaab652197ae345f17f904a943fe Mon Sep 17 00:00:00 2001 From: jfbu Date: Thu, 19 Oct 2017 09:23:41 +0200 Subject: [PATCH 1/3] Fix #4134: [doc] docutils.conf is not documented explicitly --- CHANGES | 1 + doc/config.rst | 16 ++++++++++++++-- 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/CHANGES b/CHANGES index 40c91af68..6ebe2c50a 100644 --- a/CHANGES +++ b/CHANGES @@ -31,6 +31,7 @@ Bugs fixed * #3692: Unable to build HTML if writing .buildinfo failed * #4152: HTML writer crashes if a field list is placed on top of the document * #4063: Sphinx crashes when labeling directive ``.. todolist::`` +* #4134: [doc] :file:`docutils.conf` is not documented explicitly Testing -------- diff --git a/doc/config.rst b/doc/config.rst index a094195e9..160cc3c5c 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -9,8 +9,20 @@ The build configuration file :synopsis: Build configuration file. The :term:`configuration directory` must contain a file named :file:`conf.py`. -This file (containing Python code) is called the "build configuration file" and -contains all configuration needed to customize Sphinx input and output behavior. +This file (containing Python code) is called the "build configuration file" +and contains (almost) all configuration needed to customize Sphinx input +and output behavior. + + An optional file `docutils.conf`_ can be added to the configuration + directory to adjust `Docutils`_ configuration if not otherwise overriden or + set by Sphinx; this applies in particular to the `Docutils smart_quotes + setting`_. + + .. _`docutils`: http://docutils.sourceforge.net/ + + .. _`docutils.conf`: http://docutils.sourceforge.net/docs/user/config.html + + .. _`Docutils smart_quotes setting`: http://docutils.sourceforge.net/docs/user/config.html#smart-quotes The configuration file is executed as Python code at build time (using :func:`execfile`, and with the current directory set to its containing From 6a897af1d9e22c0f933edeee7714114a03ff2b61 Mon Sep 17 00:00:00 2001 From: jfbu Date: Thu, 19 Oct 2017 09:56:14 +0200 Subject: [PATCH 2/3] Clarify docs about ``html_use_smartypants`` deprecation --- doc/config.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/config.rst b/doc/config.rst index 160cc3c5c..3dbdbd1a7 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -781,8 +781,8 @@ that use Sphinx's HTMLWriter class. entities. Default: ``True``. .. deprecated:: 1.6 - Use the `smart_quotes option`_ in the Docutils configuration file - (``docutils.conf``) instead. + To disable or customize smart quotes, use the Docutils configuration file + (``docutils.conf``) instead to set there its `smart_quotes option`_. .. _`smart_quotes option`: http://docutils.sourceforge.net/docs/user/config.html#smart-quotes From 5dbfc43ddada57a3b7bf6ee4cf1e8e07a6a58db2 Mon Sep 17 00:00:00 2001 From: jfbu Date: Thu, 19 Oct 2017 10:00:08 +0200 Subject: [PATCH 3/3] Make clearer that Sphinx applies Smart quotes by default modified: doc/config.rst --- doc/config.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/config.rst b/doc/config.rst index 3dbdbd1a7..e96c075e9 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -16,7 +16,7 @@ and output behavior. An optional file `docutils.conf`_ can be added to the configuration directory to adjust `Docutils`_ configuration if not otherwise overriden or set by Sphinx; this applies in particular to the `Docutils smart_quotes - setting`_. + setting`_ (Note that Sphinx applies smart quotes transform by default.) .. _`docutils`: http://docutils.sourceforge.net/