classification
Title: when building docs on Debian 7 --> ERROR: Error in "note" directive
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.araujo, ezio.melotti, georg.brandl, python-dev, r.david.murray, sandro.tosi, tshepang
Priority: normal Keywords: patch

Created on 2012-12-29 00:03 by tshepang, last changed 2014-03-13 19:47 by tshepang. This issue is now closed.

Files
File name Uploaded Description Edit
remove-directives-warnings.diff tshepang, 2012-12-29 15:27 review
remove-directives-warnings-2.7.diff tshepang, 2012-12-29 15:59
Messages (25)
msg178443 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-12-29 00:03
I am running Debian 7, which has sphinx is1.1.3+dfsg-4.

When I run

$ python tools/sphinx-build.py -bhtml . build/

I get a whole bunch of errors:

Making output directory...
Running Sphinx v1.1.3
loading pickled environment... not yet created
building [html]: targets for 435 source files that are out of date
updating environment: 435 added, 0 changed, 0 removed
reading sources... [100%] whatsnew/index                                                                                                                                
/home/wena/src/python/cpython/Doc/c-api/arg.rst:47: ERROR: Error in "note" directive:
invalid option block.

.. note::
   For all ``#`` variants of formats (``s#``, ``y#``, etc.), the type of
   the length argument (int or :c:type:`Py_ssize_t`) is controlled by
   defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including
   :file:`Python.h`.  If the macro was defined, length is a
   :c:type:`Py_ssize_t` rather than an :c:type:`int`. This behavior will change
   in a future Python version to only support :c:type:`Py_ssize_t` and
   drop :c:type:`int` support. It is best to always define :c:macro:`PY_SSIZE_T_CLEAN`.
/home/wena/src/python/cpython/Doc/c-api/init.rst:547: ERROR: Error in "note" directive:
invalid option block.

.. note::
   When only the main thread exists, no GIL operations are needed. This is a
   common situation (most Python programs do not use threads), and the lock
   operations slow the interpreter down a bit. Therefore, the lock is not
   created initially.  This situation is equivalent to having acquired the lock:
   when there is only a single thread, all object accesses are safe.  Therefore,
   when this function initializes the global interpreter lock, it also acquires
   it.  Before the Python :mod:`_thread` module creates a new thread, knowing
   that either it has the lock or the lock hasn't been created yet, it calls
   :c:func:`PyEval_InitThreads`.  When this call returns, it is guaranteed that
   the lock has been created and that the calling thread has acquired it.

   It is **not** safe to call this function when it is unknown which thread (if
   any) currently has the global interpreter lock.

   This function is not available when thread support is disabled at compile time.
/home/wena/src/python/cpython/Doc/faq/library.rst:513: ERROR: Error in "note" directive:
invalid option block.

.. note::
   To read and write binary data, it is mandatory to open the file in
   binary mode (here, passing ``"rb"`` to :func:`open`).  If you use
   ``"r"`` instead (the default), the file will be open in text mode
   and ``f.read()`` will return :class:`str` objects rather than
   :class:`bytes` objects.
/home/wena/src/python/cpython/Doc/library/fractions.rst:93: ERROR: Error in "note" directive:
invalid option block.

.. note:: From Python 3.2 onwards, you can also construct a
   :class:`Fraction` instance directly from a :class:`float`.
/home/wena/src/python/cpython/Doc/library/fractions.rst:102: ERROR: Error in "note" directive:
invalid option block.

.. note:: From Python 3.2 onwards, you can also construct a
   :class:`Fraction` instance directly from a :class:`decimal.Decimal`
   instance.
/home/wena/src/python/cpython/Doc/library/getopt.rst:12: ERROR: Error in "note" directive:
invalid option block.

.. note::
   The :mod:`getopt` module is a parser for command line options whose API is
   designed to be familiar to users of the C :c:func:`getopt` function. Users who
   are unfamiliar with the C :c:func:`getopt` function or who would like to write
   less code and get better help and error messages should consider using the
   :mod:`argparse` module instead.
/home/wena/src/python/cpython/Doc/library/io.rst:678: ERROR: Error in "warning" directive:
invalid option block.

.. warning::
   :class:`BufferedRWPair` does not attempt to synchronize accesses to
   its underlying raw streams.  You should not pass it the same object
   as reader and writer; use :class:`BufferedRandom` instead.
/home/wena/src/python/cpython/Doc/library/logging.config.rst:144: ERROR: Error in "note" directive:
invalid option block.

.. note:: Because portions of the configuration are passed through
   :func:`eval`, use of this function may open its users to a security risk.
   While the function only binds to a socket on ``localhost``, and so does
   not accept connections from remote machines, there are scenarios where
   untrusted code could be run under the account of the process which calls
   :func:`listen`. Specifically, if the process calling :func:`listen` runs
   on a multi-user machine where users cannot trust each other, then a
   malicious user could arrange to run essentially arbitrary code in a
   victim user's process, simply by connecting to the victim's
   :func:`listen` socket and sending a configuration which runs whatever
   code the attacker wants to have executed in the victim's process. This is
   especially easy to do if the default port is used, but not hard even if a
   different port is used). To avoid the risk of this happening, use the
   ``verify`` argument to :func:`listen` to prevent unrecognised
   configurations from being applied.
/home/wena/src/python/cpython/Doc/library/logging.config.rst:747: ERROR: Error in "note" directive:
invalid option block.

.. note:: Due to the use of :func:`eval` as described above, there are
   potential security risks which result from using the :func:`listen` to send
   and receive configurations via sockets. The risks are limited to where
   multiple users with no mutual trust run code on the same machine; see the
   :func:`listen` documentation for more information.
/home/wena/src/python/cpython/Doc/library/os.rst:263: ERROR: Error in "note" directive:
invalid option block.

.. note:: On Mac OS X, :func:`getgroups` behavior differs somewhat from
   other Unix platforms. If the Python interpreter was built with a
   deployment target of :const:`10.5` or earlier, :func:`getgroups` returns
   the list of effective group ids associated with the current user process;
   this list is limited to a system-defined number of entries, typically 16,
   and may be modified by calls to :func:`setgroups` if suitably privileged.
   If built with a deployment target greater than :const:`10.5`,
   :func:`getgroups` returns the current group access list for the user
   associated with the effective user id of the process; the group access
   list may change over the lifetime of the process, it is not affected by
   calls to :func:`setgroups`, and its length is not limited to 16.  The
   deployment target value, :const:`MACOSX_DEPLOYMENT_TARGET`, can be
   obtained with :func:`sysconfig.get_config_var`.
/home/wena/src/python/cpython/Doc/library/pkgutil.rst:148: ERROR: Error in "note" directive:
invalid option block.

.. note::
   Only works for a :term:`finder` which defines an ``iter_modules()``
   method. This interface is non-standard, so the module also provides
   implementations for :class:`importlib.machinery.FileFinder` and
   :class:`zipimport.zipimporter`.
/home/wena/src/python/cpython/Doc/library/pkgutil.rst:186: ERROR: Error in "note" directive:
invalid option block.

.. note::
   Only works for a :term:`finder` which defines an ``iter_modules()``
   method. This interface is non-standard, so the module also provides
   implementations for :class:`importlib.machinery.FileFinder` and
   :class:`zipimport.zipimporter`.
/home/wena/src/python/cpython/Doc/library/socket.rst:728: ERROR: Error in "note" directive:
invalid option block.

.. note::
   :meth:`close()` releases the resource associated with a connection but
   does not necessarily close the connection immediately.  If you want
   to close the connection in a timely fashion, call :meth:`shutdown()`
   before :meth:`close()`.
/home/wena/src/python/cpython/Doc/library/ssl.rst:609: ERROR: Error in "note" directive:
invalid option block.

.. note::
   To validate a certificate for a particular service, you can use the
   :func:`match_hostname` function.
/home/wena/src/python/cpython/Doc/library/sys.rst:245: ERROR: Error in "note" directive:
invalid option block.

.. note:: If a :ref:`virtual environment <venv-def>` is in effect, this
   value will be changed in ``site.py`` to point to the virtual environment.
   The value for the Python installation will still be available, via
   :data:`base_exec_prefix`.
/home/wena/src/python/cpython/Doc/library/test.rst:201: ERROR: Error in "note" directive:
invalid option block.

.. note::
   :mod:`test.support` is not a public module.  It is documented here to help
   Python developers write tests.  The API of this module is subject to change
   without backwards compatibility concerns between releases.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] whatsnew/index                                                                                                                                 
writing additional files... genindex py-modindex search download index opensearch
copying images... [100%] library/turtle-star.png                                                                                                                        
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 16 warnings.
msg178448 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2012-12-29 00:40
Hello Tshepang,
the documentation is not compatible with Sphinx versions different than the one the Makefile will download (in this case it's 1.0.7 for all active branches). I'd suggest to build the doc with just

$ make -C Doc html

and it will fetch the needed modules (at the correct version) and build the html version of the documentation in Doc/build/html/.

I'm inclined to close this issue as invalid, but I'd like to hear from your first.

Regards,
Sandro
msg178458 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-12-29 01:33
It is my preference to be able to build all of CPython with the
already-installed distro packages, instead of pulling in foreign ones.
Any reason why not use later versions? Can't the docs be written such
that they can run on various versions of these tools anyway?
msg178480 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-12-29 08:10
In this case it's more of a docutils version problem, I would guess. Tshepang, can you find out your docutils version?

But "proper" use of the note directive is with an empty line, so we should fix these instances anyway.
msg178484 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-12-29 12:42
docutils 0.8.1-8
msg178486 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2012-12-29 12:57
On Sat, Dec 29, 2012 at 4:33 AM, Tshepang Lekhonkhobe
<report@bugs.python.org> wrote:
> It is my preference to be able to build all of CPython with the
> already-installed distro packages, instead of pulling in foreign ones.

IMO, I think with a project as bit as CPython, you should leave you
personal preferences apart and use (as much as possible) the tools the
project has decided to use: having a consistent set of tools to build
doc across everyone/everything (like auto-build doc machines) trying
to generate the doc is the proper way to handle it.

> Any reason why not use later versions?

no-one has done the work of testing, preparation and migration: do you
volunteer? :)

> Can't the docs be written such
> that they can run on various versions of these tools anyway?

Not always, but of course, as Georg said, if for note directive we can
have a syntax working with current and higher versions of
sphinx/docutils, that's ok to do it.

I only think that using a non-standard set of doc-build-tools is to be
discouraged, and sticking to what Makefile will fetch is the proper
way to build the doc and contribute to it.

Regards,
--
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi
msg178489 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-12-29 13:07
> no-one has done the work of testing, preparation and migration: do you
> volunteer? :)

What needs doing exactly? I would volunteer if guided. I normally
build with the Debian-provided tools, and the docs look good, all but
those note directive errors.

Also, can I submit a patch that adds the missing newlines, or will
some committer take care of it, or does this need further discussion?
msg178492 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2012-12-29 13:23
On Sat, Dec 29, 2012 at 4:07 PM, Tshepang Lekhonkhobe
<report@bugs.python.org> wrote:
>> no-one has done the work of testing, preparation and migration: do you
>> volunteer? :)
>
> What needs doing exactly? I would volunteer if guided. I normally

(you always can't expect to be guided) it's not much more than

- update sphinx (and the other tools it depends on, if needed).
- fix what's broken or what needs updating
- verify the doc is ok

for any supported branches.

> Also, can I submit a patch that adds the missing newlines, or will
> some committer take care of it, or does this need further discussion?

it won't hurt to have a patch. But please build the doc it with the
CPython selected tools before submitting the patch, and verifying the
doc sections you've changed are still ok.
msg178503 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-12-29 15:27
I have tested the attached patch using official tools (make -C Doc html) and the only differences, between before and after, are:

* The genindex files, where some of the keywords that are duplicated in the documentation would end up getting randomly swapped around. An example is "DEDENT token", which appears twice in the documentation (see http://docs.python.org/3/genindex-D.html). In its case, the 1st url points to where the 2nd url used to point and vice versa.

* objects.inv: related to genindex changes?

* searchindex.js: also related to genindex changes?

I suspect these differences do not matter though, since these are just indexes.
msg178506 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-12-29 15:52
The previous patch applies cleanly to 3.3 and 3.4. I am now attaching one that applies cleanly to 3.2.
msg178507 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-12-29 15:59
And this one patch applies to 2.7.
msg178518 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-12-29 17:52
LGTM.
msg188959 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2013-05-11 22:02
ping
msg188964 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2013-05-11 22:27
@ezio why remove 3.2 from applicable versions
msg188965 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-05-11 22:29
3.2 only gets security fixes.
msg188994 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2013-05-12 09:41
Ok. I thought doc fixes were exempt. Strange policy there.
msg188996 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-05-12 10:02
Please do not comment on policies if you don't understand our release system.
msg189583 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-05-19 12:21
Tshepang: see the 'Development Cycle' section of the devguide.  Only security related commits are allowed to security branches, and since the docs are part of the source tree, that means no doc commits.  One reason for this is the same reason we only have one maintenance release (ignoring 2.7, it is an exception), and is a matter of practicality: reducing the load on developers.
msg189587 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2013-05-19 13:28
@murray thanks for the clarification; I saw that part of the devguide, but wasn't sure if doc fixes/improvements were exempt (even if not mentioned)
msg189615 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-05-19 18:49
An additional reason is that docs of branches in security mode are not rebuilt and published, so changes would be useless.
msg199355 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2013-10-09 23:07
BTW, these patches still apply, one to 2.7 and another to 3.3 and 3.4. They are pretty much harmless, so do not be afraid to accept them.
msg213331 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-03-12 23:36
New changeset ca43fa662b0d by Éric Araujo in branch '2.7':
Fix note markup (#16805).
http://hg.python.org/cpython/rev/ca43fa662b0d
msg213337 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-03-12 23:52
New changeset 9dc653f48357 by Éric Araujo in branch '3.3':
Fix note markup (#16805).
http://hg.python.org/cpython/rev/9dc653f48357

New changeset 44e815a33ae3 by Éric Araujo in branch 'default':
Merge 3.3 (#16805)
http://hg.python.org/cpython/rev/44e815a33ae3
msg213338 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-03-12 23:53
Georg said LGTM, I applied the patches.  Thanks!
msg213451 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2014-03-13 19:47
thanks much for the commit
History
Date User Action Args
2014-03-13 19:47:16tshepangsetmessages: + msg213451
2014-03-12 23:53:48eric.araujosetstatus: open -> closed
resolution: fixed
messages: + msg213338

stage: patch review -> resolved
2014-03-12 23:52:04python-devsetmessages: + msg213337
2014-03-12 23:36:17python-devsetnosy: + python-dev
messages: + msg213331
2013-10-09 23:07:19tshepangsetmessages: + msg199355
2013-10-09 23:06:01tshepangsetfiles: - remove-directives-warnings-3.2.diff
2013-05-19 18:49:18eric.araujosetmessages: + msg189615
2013-05-19 13:28:24tshepangsetmessages: + msg189587
2013-05-19 12:21:38r.david.murraysetnosy: + r.david.murray
messages: + msg189583
2013-05-12 10:02:02georg.brandlsetmessages: + msg188996
2013-05-12 09:41:23tshepangsetmessages: + msg188994
2013-05-11 22:29:53ezio.melottisetmessages: + msg188965
2013-05-11 22:27:28tshepangsetmessages: + msg188964
2013-05-11 22:03:03ezio.melottisetnosy: + ezio.melotti
stage: patch review
type: behavior

versions: - Python 3.2
2013-05-11 22:02:12tshepangsetmessages: + msg188959
2013-01-08 12:30:35eric.araujosetnosy: + eric.araujo
2012-12-29 17:52:08georg.brandlsetmessages: + msg178518
2012-12-29 15:59:07tshepangsetfiles: + remove-directives-warnings-2.7.diff

messages: + msg178507
versions: + Python 2.7, Python 3.2
2012-12-29 15:52:07tshepangsetfiles: + remove-directives-warnings-3.2.diff

messages: + msg178506
versions: + Python 3.3
2012-12-29 15:27:23tshepangsetfiles: + remove-directives-warnings.diff
keywords: + patch
messages: + msg178503
2012-12-29 13:23:01sandro.tosisetmessages: + msg178492
2012-12-29 13:07:06tshepangsetmessages: + msg178489
2012-12-29 12:57:52sandro.tosisetmessages: + msg178486
2012-12-29 12:42:16tshepangsetmessages: + msg178484
2012-12-29 08:10:08georg.brandlsetnosy: + georg.brandl
messages: + msg178480
2012-12-29 01:33:41tshepangsetmessages: + msg178458
2012-12-29 00:40:00sandro.tosisetnosy: + sandro.tosi
messages: + msg178448
2012-12-29 00:03:55tshepangcreate