From 453290fc665efff6a698cac5a7503caaf0ca3a84 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 11 Jan 2014 19:54:47 +0100 Subject: [PATCH 01/15] doc: make it more prominent that sub-toctrees shouldnt get :numbered: Should be enforced programmatically at some point! --- doc/markup/toctree.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst index 41c265f85..9316e69a7 100644 --- a/doc/markup/toctree.rst +++ b/doc/markup/toctree.rst @@ -68,8 +68,8 @@ tables of contents. The ``toctree`` directive is the central element. **Section numbering** - If you want to have section numbers even in HTML output, give the toctree a - ``numbered`` option. For example:: + If you want to have section numbers even in HTML output, give the + **toplevel** toctree a ``numbered`` option. For example:: .. toctree:: :numbered: From 8d2715ebd993665b4e45d13b76853edb4862a6a6 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 11 Jan 2014 19:54:58 +0100 Subject: [PATCH 02/15] html builder: add missing "done" output --- sphinx/builders/html.py | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index ecc8a3b66..dd62e2ba7 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -620,6 +620,7 @@ class StandaloneHTMLBuilder(Builder): self.warn('html_extra_path entry %r does not exist' % entry) continue copy_static_entry(entry, self.outdir, self) + self.info('done') def write_buildinfo(self): # write build info file From 32d1ebec56717faedcfa6e94aaa9872897fe77ff Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 11 Jan 2014 20:13:14 +0100 Subject: [PATCH 03/15] Closes #949: Update the tabulary.sty packed with Sphinx. --- CHANGES | 2 ++ sphinx/texinputs/tabulary.sty | 9 +++------ 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/CHANGES b/CHANGES index 8c4e514ef..2d96638df 100644 --- a/CHANGES +++ b/CHANGES @@ -51,6 +51,8 @@ Bugs fixed * #929: Support parsed-literal blocks in LaTeX output correctly. +* #949: Update the tabulary.sty packed with Sphinx. + Documentation ------------- diff --git a/sphinx/texinputs/tabulary.sty b/sphinx/texinputs/tabulary.sty index ba83c0afb..7ea572c12 100644 --- a/sphinx/texinputs/tabulary.sty +++ b/sphinx/texinputs/tabulary.sty @@ -8,13 +8,13 @@ %% DRAFT VERSION %% %% File `tabulary.dtx'. -%% Copyright (C) 1995 1996 2003 David Carlisle +%% Copyright (C) 1995 1996 2003 2008 David Carlisle %% This file may be distributed under the terms of the LPPL. %% See 00readme.txt for details. %% \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{tabulary} - [2007/10/02 v0.9 tabulary package (DPC)] + [2008/12/01 v0.9 tabulary package (DPC)] \RequirePackage{array} \catcode`\Z=14 \DeclareOption{debugshow}{\catcode`\Z=9\relax} @@ -109,8 +109,6 @@ Z \string\tymax: \the\tymax^^J}% \global\advance\TY@linewidth-#1\relax} \def\endtabulary{% \gdef\@halignto{}% - \let\TY@footnote\footnote% - \def\footnote{}% prevent footnotes from doing anything \expandafter\TY@tab\the\toks@ \crcr\omit {\xdef\TY@save@row{}% @@ -174,7 +172,6 @@ Z \message{> tymin}% \TY@checkmin \TY@count\z@ \let\TY@box\TY@box@v - \let\footnote\TY@footnote % restore footnotes {\expandafter\TY@final\the\toks@\endTY@final}% \count@\z@ \@tempswatrue @@ -195,7 +192,7 @@ Z \message{> tymin}% \let\TY@checkmin\relax \ifdim\TY@tablewidth>\z@ \Gscale@div\TY@ratio\TY@linewidth\TY@tablewidth - \ifdim\TY@tablewidth <\linewidth + \ifdim\TY@tablewidth <\TY@linewidth \def\TY@ratio{1}% \fi \else From 48524dcecc312933291a3340f4a46b8bda075b0b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 11 Jan 2014 20:18:37 +0100 Subject: [PATCH 04/15] Closes #983: clarify "docstitle" behavior with singlehtml --- doc/templating.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/templating.rst b/doc/templating.rst index b9dfc683b..b9561b698 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -251,7 +251,8 @@ in the future. .. data:: docstitle - The title of the documentation (the value of :confval:`html_title`). + The title of the documentation (the value of :confval:`html_title`), except + when the "single-file" builder is used, when it is set to ``None``. .. data:: embedded From 8436f07c40911eb931b28cfe36566d007690c84c Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 11 Jan 2014 20:54:42 +0100 Subject: [PATCH 05/15] Closes #1050: Add anonymous labels into ``objects.inv`` to be referenced via intersphinx. --- CHANGES | 3 +++ sphinx/domains/std.py | 5 +++++ 2 files changed, 8 insertions(+) diff --git a/CHANGES b/CHANGES index 2d96638df..963c5b2b4 100644 --- a/CHANGES +++ b/CHANGES @@ -53,6 +53,9 @@ Bugs fixed * #949: Update the tabulary.sty packed with Sphinx. +* #1050: Add anonymous labels into ``objects.inv`` to be referenced via + intersphinx. + Documentation ------------- diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py index 50e519fab..d5c92387d 100644 --- a/sphinx/domains/std.py +++ b/sphinx/domains/std.py @@ -612,6 +612,11 @@ class StandardDomain(Domain): self.object_types[type].attrs['searchprio']) for name, info in self.data['labels'].iteritems(): yield (name, info[2], 'label', info[0], info[1], -1) + # add anonymous-only labels as well + non_anon_labels = set(self.data['labels']) + for name, info in self.data['anonlabels'].iteritems(): + if name not in non_anon_labels: + yield (name, name, 'label', info[0], info[1], -1) def get_type_name(self, type, primary=False): # never prepend "Default" From e38156856e58d32e81ae21b689affdc85cd20128 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 11 Jan 2014 21:00:31 +0100 Subject: [PATCH 06/15] Closes #1095: Fix print-media stylesheet being included always in the "scrolls" theme. Also fixes wrong additions of stylesheets and scripts in haiku theme (probably copy-paste error from scrolls). --- CHANGES | 3 +++ sphinx/themes/haiku/layout.html | 2 -- sphinx/themes/scrolls/static/print.css | 12 +++++++----- 3 files changed, 10 insertions(+), 7 deletions(-) diff --git a/CHANGES b/CHANGES index 963c5b2b4..3b56c3aa6 100644 --- a/CHANGES +++ b/CHANGES @@ -56,6 +56,9 @@ Bugs fixed * #1050: Add anonymous labels into ``objects.inv`` to be referenced via intersphinx. +* #1095: Fix print-media stylesheet being included always in the "scrolls" + theme. + Documentation ------------- diff --git a/sphinx/themes/haiku/layout.html b/sphinx/themes/haiku/layout.html index 337d0ca24..0c6b41e7c 100644 --- a/sphinx/themes/haiku/layout.html +++ b/sphinx/themes/haiku/layout.html @@ -8,8 +8,6 @@ :license: BSD, see LICENSE for details. #} {%- extends "basic/layout.html" %} -{% set script_files = script_files + ['_static/theme_extras.js'] %} -{% set css_files = css_files + ['_static/print.css'] %} {# do not display relbars #} {% block relbar1 %}{% endblock %} diff --git a/sphinx/themes/scrolls/static/print.css b/sphinx/themes/scrolls/static/print.css index fb633d879..715d90ab6 100644 --- a/sphinx/themes/scrolls/static/print.css +++ b/sphinx/themes/scrolls/static/print.css @@ -1,5 +1,7 @@ -div.header, div.relnav, #toc { display: none; } -#contentwrapper { padding: 0; margin: 0; border: none; } -body { color: black; background-color: white; } -div.footer { border-top: 1px solid #888; color: #888; margin-top: 1cm; } -div.footer a { text-decoration: none; } +@media print { + div.header, div.relnav, #toc { display: none; } + #contentwrapper { padding: 0; margin: 0; border: none; } + body { color: black; background-color: white; } + div.footer { border-top: 1px solid #888; color: #888; margin-top: 1cm; } + div.footer a { text-decoration: none; } +} From d38c5cac8d418f8f1a7fa2831e51c31618e6dae0 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 11 Jan 2014 21:03:56 +0100 Subject: [PATCH 07/15] Closes #1082: clarify that html_title default value does not really have placeholders --- doc/config.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/config.rst b/doc/config.rst index 70ccd26eb..ac6d506b2 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -472,8 +472,8 @@ that use Sphinx' HTMLWriter class. The "title" for HTML documentation generated with Sphinx' own templates. This is appended to the ```` tag of individual pages, and used in the navigation bar as the "topmost" element. It defaults to :samp:`'{<project>} - v{<revision>} documentation'`, where the placeholders are replaced by the - config values of the same name. + v{<revision>} documentation'` (with the values coming from the config + values). .. confval:: html_short_title From 7b7579765d600691cfbd96ea5413aa3a8ee9052b Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 11 Jan 2014 21:08:52 +0100 Subject: [PATCH 08/15] Closes #1085: Fix current classname not getting set if class description has ``:noindex:`` set. --- CHANGES | 3 +++ sphinx/directives/__init__.py | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 3b56c3aa6..0304cb55b 100644 --- a/CHANGES +++ b/CHANGES @@ -59,6 +59,9 @@ Bugs fixed * #1095: Fix print-media stylesheet being included always in the "scrolls" theme. +* #1085: Fix current classname not getting set if class description has + ``:noindex:`` set. + Documentation ------------- diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py index 388522dca..52e6e6fba 100644 --- a/sphinx/directives/__init__.py +++ b/sphinx/directives/__init__.py @@ -149,10 +149,10 @@ class ObjectDescription(Directive): signode.clear() signode += addnodes.desc_name(sig, sig) continue # we don't want an index entry here + self.names.append(name) if not noindex and name not in self.names: # only add target and index entry if this is the first # description of the object with this name in this desc block - self.names.append(name) self.add_target_and_index(name, sig, signode) contentnode = addnodes.desc_content() From b23f0489f4008187b9b6cd4d86145da615f22035 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 11 Jan 2014 21:40:26 +0100 Subject: [PATCH 09/15] fix oversight in last commit --- sphinx/directives/__init__.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py index 52e6e6fba..d2b70b82f 100644 --- a/sphinx/directives/__init__.py +++ b/sphinx/directives/__init__.py @@ -149,11 +149,12 @@ class ObjectDescription(Directive): signode.clear() signode += addnodes.desc_name(sig, sig) continue # we don't want an index entry here - self.names.append(name) - if not noindex and name not in self.names: - # only add target and index entry if this is the first - # description of the object with this name in this desc block - self.add_target_and_index(name, sig, signode) + if name not in self.names: + self.names.append(name) + if not noindex: + # only add target and index entry if this is the first + # description of the object with this name in this desc block + self.add_target_and_index(name, sig, signode) contentnode = addnodes.desc_content() node.append(contentnode) From 9d25862700fba60825eb2a5ecfc04170e4749ead Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 12 Jan 2014 12:44:36 +0100 Subject: [PATCH 10/15] add link to "write the docs", move hosting chapter to home page --- doc/_templates/index.html | 15 ++++++++++++--- doc/intro.rst | 13 ++++--------- 2 files changed, 16 insertions(+), 12 deletions(-) diff --git a/doc/_templates/index.html b/doc/_templates/index.html index 0739191e5..e6ef91784 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -21,7 +21,7 @@ </p> <ul> <li>{%trans%}<b>Output formats:</b> HTML (including Windows HTML Help), LaTeX (for - printable PDF versions), Texinfo, manual pages, plain text{%endtrans%}</li> + printable PDF versions), ePub, Texinfo, manual pages, plain text{%endtrans%}</li> <li>{%trans%}<b>Extensive cross-references:</b> semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information{%endtrans%}</li> @@ -85,7 +85,16 @@ of this documentation, thanks to the Japanese Sphinx user group.{%endtrans%}</p> <p>{%trans%}A Japanese book about Sphinx has been published by O'Reilly: <a href="http://www.oreilly.co.jp/books/9784873116488/">Sphinxをはじめよう / - Learning Sphinx</a>:{%endtrans%}</p> - <p><img src="{{ pathto("_static/bookcover.png", 1) }}"/></p> + Learning Sphinx</a>.{%endtrans%}</p> + <!-- <p><img src="{{ pathto("_static/bookcover.png", 1) }}"/></p> --> + + + <h2>{%trans%}Hosting{%endtrans%}</h2> + + <p>{%trans%}Need a place to host your Sphinx docs? + <a href="http://readthedocs.org">readthedocs.org</a> hosts a lot of Sphinx docs + already, and integrates well with projects' source control. It also features a + powerful built-in search that exceeds the possibilities of Sphinx' JavaScript-based + offline search.{%endtrans%}</p> {% endblock %} diff --git a/doc/intro.rst b/doc/intro.rst index 24760aa9e..d1cab1c84 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -16,6 +16,10 @@ Though there is support for that kind of docs as well (which is intended to be freely mixed with hand-written content), if you need pure API docs have a look at `Epydoc <http://epydoc.sf.net/>`_, which also understands reST. +For a great "introduction" to writing docs in general -- the whys and hows, see +also `Write the docs <http://write-the-docs.readthedocs.org/>`_, written by Eric +Holscher. + Conversion from other systems ----------------------------- @@ -66,12 +70,3 @@ Usage See :doc:`tutorial` for an introduction. It also contains links to more advanced sections in this manual for the topics it discusses. - - -Hosting -------- - -Need a place to host your Sphinx docs? `readthedocs.org -<http://readthedocs.org>`_ hosts a lot of Sphinx docs already, and integrates -well with projects' source control. It also features a powerful built-in search -that exceeds the possibilities of Sphinx' JavaScript-based offline search. From 1ddedb523ea32ab1101e6c21af14beb41a230fb7 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 12 Jan 2014 12:47:37 +0100 Subject: [PATCH 11/15] some more markup in changelog --- CHANGES | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CHANGES b/CHANGES index 0304cb55b..82595c1b1 100644 --- a/CHANGES +++ b/CHANGES @@ -10,12 +10,12 @@ Bugs fixed * #1337: Fix autodoc with ``autoclass_content="both"`` uses useless ``object.__init__`` docstring when class does not have ``__init__``. - This caused by a change for #1138. + This was caused by a change for #1138. * #1340: Can't search alphabetical words on the HTML quick search generated with language='ja'. -* #1319: Do not crash if the ``html_logo`` file does not exist. +* #1319: Do not crash if the :confval:`html_logo` file does not exist. * #603: Do not use the HTML-ized title for building the search index (that resulted in "literal" being found on every page with a literal in the @@ -30,8 +30,8 @@ Bugs fixed * #932: autodoc: Do not crash if ``__doc__`` is not a string. -* #933: Do not crash if an ``:option:`` value is malformed (contains spaces - but no option name). +* #933: Do not crash if an :rst:role:`option` value is malformed (contains + spaces but no option name). * #908: On Python 3, handle error messages from LaTeX correctly in the pngmath extension. @@ -41,7 +41,7 @@ Bugs fixed * #923: Take the entire LaTeX document into account when caching pngmath-generated images. This rebuilds them correctly when - ``pngmath_latex_preamble`` changes. + :confval:`pngmath_latex_preamble` changes. * #901: Emit a warning when using docutils' new "math" markup without a Sphinx math extension active. @@ -54,7 +54,7 @@ Bugs fixed * #949: Update the tabulary.sty packed with Sphinx. * #1050: Add anonymous labels into ``objects.inv`` to be referenced via - intersphinx. + :mod:`~sphinx.ext.intersphinx`. * #1095: Fix print-media stylesheet being included always in the "scrolls" theme. From 31aed073864aefee3ee072b740cc92164d73656d Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 12 Jan 2014 16:07:21 +0100 Subject: [PATCH 12/15] Closes #1156: bring manpage up to scratch with current options and builders. --- doc/man/sphinx-build.rst | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index 0a5d4abb9..aa1d71c64 100644 --- a/doc/man/sphinx-build.rst +++ b/doc/man/sphinx-build.rst @@ -32,6 +32,13 @@ List of available builders: html HTML file generation. This is the default builder. +dirhtml + HTML file generation with every HTML file named "index.html" in a separate + directory. + +singlehtml + HTML file generation with all content in a single HTML file. + htmlhelp Generates files for CHM (compiled help files) generation. @@ -51,9 +58,15 @@ texinfo Generates Texinfo output that can be processed by :program:`makeinfo` to generate an Info document. +epub + Generates an ePub e-book version of the HTML output. + text Generates a plain-text version of the documentation. +gettext + Generates Gettext message catalogs for content translation. + changes Generates HTML files listing changed/added/deprecated items for the current version of the documented project. @@ -81,20 +94,24 @@ Options output for new and changed files is generated. -E Ignore cached files, forces to re-read all source files from disk. +-d <path> Path to cached files; defaults to <outdir>/.doctrees. +-j <N> Build in parallel with N processes where possible. -c <path> Locate the conf.py file in the specified path instead of <sourcedir>. -C Specify that no conf.py file at all is to be used. Configuration can only be set with the -D option. -D <setting=value> Override a setting from the configuration file. --d <path> Path to cached files; defaults to <outdir>/.doctrees. +-t <tag> Define *tag* for use in "only" blocks. -A <name=value> Pass a value into the HTML templates (only for HTML builders). -n Run in nit-picky mode, warn about all missing references. +-v Increase verbosity (can be repeated). -N Prevent colored output. -q Quiet operation, just print warnings and errors on stderr. -Q Very quiet operation, don't print anything except for errors. -w <file> Write warnings and errors into the given file, in addition to stderr. -W Turn warnings into errors. +-T Show full traceback on exception. -P Run Pdb on exception. From 521719f8a1f4fb907d7f7384955d1f9db530494f Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 12 Jan 2014 16:20:13 +0100 Subject: [PATCH 13/15] Closes #1181: Report option errors in autodoc directives more gracefully. --- CHANGES | 2 ++ sphinx/ext/autodoc.py | 11 +++++++++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/CHANGES b/CHANGES index 82595c1b1..50f63252e 100644 --- a/CHANGES +++ b/CHANGES @@ -62,6 +62,8 @@ Bugs fixed * #1085: Fix current classname not getting set if class description has ``:noindex:`` set. +* #1181: Report option errors in autodoc directives more gracefully. + Documentation ------------- diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 05996f9e5..ad7b02bbb 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -1384,8 +1384,15 @@ class AutoDirective(Directive): not negated: self.options[flag] = None # process the options with the selected documenter's option_spec - self.genopt = Options(assemble_option_dict( - self.options.items(), doc_class.option_spec)) + try: + self.genopt = Options(assemble_option_dict( + self.options.items(), doc_class.option_spec)) + except (KeyError, ValueError, TypeError), err: + # an option is either unknown or has a wrong type + msg = self.reporter.error('An option to %s is either unknown or ' + 'has an invalid value: %s' % (self.name, err), + line=self.lineno) + return [msg] # generate the output documenter = doc_class(self, self.arguments[0]) documenter.generate(more_content=self.content) From 3f1235e2ea3361c6b0bacf0e262c48699851aed3 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 12 Jan 2014 16:28:27 +0100 Subject: [PATCH 14/15] doc: note that "image" paths should not have spaces. --- doc/rest.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/rest.rst b/doc/rest.rst index ccfdf11d5..b35ebc91d 100644 --- a/doc/rest.rst +++ b/doc/rest.rst @@ -373,6 +373,8 @@ For instance, if the file name ``gnu.*`` was given and two files :file:`gnu.pdf` and :file:`gnu.png` existed in the source tree, the LaTeX builder would choose the former, while the HTML builder would prefer the latter. +Note that image file names should not contain spaces. + .. versionchanged:: 0.4 Added the support for file names ending in an asterisk. From aac72f175ab52779832961a88f6e8b8e94375d21 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 12 Jan 2014 16:43:14 +0100 Subject: [PATCH 15/15] Closes #1155: Fix autodocumenting C-defined methods as attributes in Python 3. --- CHANGES | 2 ++ sphinx/ext/autodoc.py | 3 ++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 50f63252e..53974c525 100644 --- a/CHANGES +++ b/CHANGES @@ -64,6 +64,8 @@ Bugs fixed * #1181: Report option errors in autodoc directives more gracefully. +* #1155: Fix autodocumenting C-defined methods as attributes in Python 3. + Documentation ------------- diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index ad7b02bbb..9d950a754 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -1244,7 +1244,8 @@ class AttributeDocumenter(ClassLevelDocumenter): def can_document_member(cls, member, membername, isattr, parent): isdatadesc = isdescriptor(member) and not \ isinstance(member, cls.method_types) and not \ - type(member).__name__ in ("type", "method_descriptor") + type(member).__name__ in ("type", "method_descriptor", + "instancemethod") return isdatadesc or (not isinstance(parent, ModuleDocumenter) and not inspect.isroutine(member) and not isinstance(member, class_types))