From ce3fa678f4e881f65a7f783be29aea548d72395e Mon Sep 17 00:00:00 2001 From: Benoit Boissinot Date: Tue, 4 Nov 2008 02:34:12 +0100 Subject: [PATCH 01/12] change tracker url --- TODO | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TODO b/TODO index 11ac340cf6..dbfd72b8d0 100644 --- a/TODO +++ b/TODO @@ -2,5 +2,5 @@ Sphinx TODO =========== All todo items are now tracked as issues in the Sphinx issue tracker at -. +. From 39bb91977ccc4e09097b5ec803e007c96eeef778 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 4 Nov 2008 08:17:59 +0100 Subject: [PATCH 02/12] Re-add spacing between parameter name and description. --- sphinx/directives/desc.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/directives/desc.py b/sphinx/directives/desc.py index 91eba09ed7..a737489203 100644 --- a/sphinx/directives/desc.py +++ b/sphinx/directives/desc.py @@ -147,7 +147,7 @@ def handle_doc_fields(node): dlitem = nodes.list_item() dlpar = nodes.paragraph() dlpar += nodes.emphasis(obj, obj) - dlpar += nodes.Text('', ' -- ') + dlpar += nodes.Text(' -- ', ' -- ') dlpar += children param_nodes[obj] = dlpar dlitem += dlpar From e666b6d203c1b763535c6a29271d0141b72c5969 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 4 Nov 2008 08:20:18 +0100 Subject: [PATCH 03/12] Correct parameter name in example. --- doc/markup/desc.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/markup/desc.rst b/doc/markup/desc.rst index 4478e4bbc0..f121d23d71 100644 --- a/doc/markup/desc.rst +++ b/doc/markup/desc.rst @@ -288,7 +288,7 @@ explained by an example:: Format the exception with a traceback. - :param object: exception type + :param etype: exception type :param value: exception value :param tb: traceback object :param limit: maximum number of stack frames to show @@ -302,7 +302,7 @@ This will render like this: Format the exception with a traceback. - :param object: exception type + :param etype: exception type :param value: exception value :param tb: traceback object :param limit: maximum number of stack frames to show From a6f09758e3510dc7d685d78a456d28eefd565779 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 4 Nov 2008 08:34:35 +0100 Subject: [PATCH 04/12] Add -A option to pass values into HTML templates. --- sphinx/__init__.py | 24 ++++++++++++++++++++++-- sphinx/builder.py | 1 + sphinx/config.py | 1 + tests/root/_templates/layout.html | 4 ++++ tests/root/conf.py | 2 ++ tests/test_build.py | 1 + 6 files changed, 31 insertions(+), 2 deletions(-) create mode 100644 tests/root/_templates/layout.html diff --git a/sphinx/__init__.py b/sphinx/__init__.py index d53fdafd24..2af1de31ab 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -39,6 +39,7 @@ Options: -b -- builder to use; default is html -c -- path where configuration file (conf.py) is located (default: same as sourcedir) -D -- override a setting in configuration + -A -- pass a value into the templates, for HTML builder -N -- do not do colored output -q -- no output on stdout, just warnings on stderr -P -- run Pdb on exception @@ -59,7 +60,7 @@ def main(argv=sys.argv): nocolor() try: - opts, args = getopt.getopt(argv[1:], 'ab:d:c:D:NEqP') + opts, args = getopt.getopt(argv[1:], 'ab:d:c:D:A:NEqP') srcdir = confdir = path.abspath(args[0]) if not path.isdir(srcdir): print >>sys.stderr, 'Error: Cannot find source directory.' @@ -89,6 +90,7 @@ def main(argv=sys.argv): freshenv = use_pdb = False status = sys.stdout confoverrides = {} + htmlcontext = {} doctreedir = path.join(outdir, '.doctrees') for opt, val in opts: if opt == '-b': @@ -107,12 +109,29 @@ def main(argv=sys.argv): 'Error: Configuration directory doesn\'t contain conf.py file.' return 1 elif opt == '-D': - key, val = val.split('=') + try: + key, val = val.split('=') + except ValueError: + print >>sys.stderr, \ + 'Error: -D option argument must be in the form name=value.' + return 1 try: val = int(val) except ValueError: pass confoverrides[key] = val + elif opt == '-A': + try: + key, val = val.split('=') + except ValueError: + print >>sys.stderr, \ + 'Error: -A option argument must be in the form name=value.' + return 1 + try: + val = int(val) + except ValueError: + pass + htmlcontext[key] = val elif opt == '-N': nocolor() elif opt == '-E': @@ -121,6 +140,7 @@ def main(argv=sys.argv): status = StringIO() elif opt == '-P': use_pdb = True + confoverrides['html_context'] = htmlcontext try: app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername, diff --git a/sphinx/builder.py b/sphinx/builder.py index d466bd7030..b3e36b4554 100644 --- a/sphinx/builder.py +++ b/sphinx/builder.py @@ -449,6 +449,7 @@ class StandaloneHTMLBuilder(Builder): logo = logo, favicon = favicon, ) + self.globalcontext.update(self.config.html_context) def get_doc_context(self, docname, body, metatags): """Collect items for the template context of a page.""" diff --git a/sphinx/config.py b/sphinx/config.py index 3da2ad8142..012668e799 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -71,6 +71,7 @@ class Config(object): html_use_opensearch = ('', False), html_file_suffix = (None, False), html_show_sphinx = (True, False), + html_context = ({}, False), # HTML help only options htmlhelp_basename = ('pydoc', False), diff --git a/tests/root/_templates/layout.html b/tests/root/_templates/layout.html new file mode 100644 index 0000000000..1f4688e605 --- /dev/null +++ b/tests/root/_templates/layout.html @@ -0,0 +1,4 @@ +{% extends "!layout.html" %} +{% block extrahead %} + +{% endblock %} diff --git a/tests/root/conf.py b/tests/root/conf.py index f814220569..8d2b276f9e 100644 --- a/tests/root/conf.py +++ b/tests/root/conf.py @@ -133,6 +133,8 @@ html_last_updated_fmt = '%b %d, %Y' # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). #html_file_suffix = '' +html_context = {'hckey': 'hcval'} + # Output file base name for HTML help builder. htmlhelp_basename = 'SphinxTestsdoc' diff --git a/tests/test_build.py b/tests/test_build.py index a3d10df16d..07a946964a 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -67,6 +67,7 @@ HTML_XPATH = { ".//a[@href='#mod.Cls']": '', }, 'contents.html': { + ".//meta[@name='hc'][@content='hcval']": '', ".//td[@class='label']": '[Ref1]', }, } From af94c013196a2381f48fd2168109854670a1462c Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 4 Nov 2008 08:40:19 +0100 Subject: [PATCH 05/12] Make the scripts executable. --- sphinx-build.py | 0 sphinx-quickstart.py | 0 2 files changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 sphinx-build.py mode change 100644 => 100755 sphinx-quickstart.py diff --git a/sphinx-build.py b/sphinx-build.py old mode 100644 new mode 100755 diff --git a/sphinx-quickstart.py b/sphinx-quickstart.py old mode 100644 new mode 100755 From 40fbd63eefff2314da7bb62710b390fea004d3a3 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 4 Nov 2008 08:41:42 +0100 Subject: [PATCH 06/12] Don't generate HTML modindex if no modules are present. --- CHANGES | 3 +++ sphinx/builder.py | 4 ++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/CHANGES b/CHANGES index 0ab7bbd239..d753c40273 100644 --- a/CHANGES +++ b/CHANGES @@ -58,6 +58,9 @@ New features added used to disable the anchor-link creation after headlines and definition links. + - Only generate a module index if there are some modules in the + documentation. + * New and changed config values: - Added support for internationalization in generated text with the diff --git a/sphinx/builder.py b/sphinx/builder.py index b3e36b4554..eaaaaf1a48 100644 --- a/sphinx/builder.py +++ b/sphinx/builder.py @@ -425,7 +425,7 @@ class StandaloneHTMLBuilder(Builder): rellinks = [] if self.config.html_use_index: rellinks.append(('genindex', _('General Index'), 'I', _('index'))) - if self.config.html_use_modindex: + if self.config.html_use_modindex and self.env.modules: rellinks.append(('modindex', _('Global Module Index'), 'M', _('modules'))) self.globalcontext = dict( @@ -559,7 +559,7 @@ class StandaloneHTMLBuilder(Builder): # the global module index - if self.config.html_use_modindex: + if self.config.html_use_modindex and self.env.modules: # the sorted list of all modules, for the global module index modules = sorted(((mn, (self.get_relative_uri('modindex', fn) + '#module-' + mn, sy, pl, dep)) From 3607d366f2026458d9dc6b31af181d65900b1b73 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 4 Nov 2008 08:43:13 +0100 Subject: [PATCH 07/12] Allow silencing all warnings with -Q. --- sphinx/__init__.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/sphinx/__init__.py b/sphinx/__init__.py index 2af1de31ab..ed6386d4ec 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -42,6 +42,7 @@ Options: -b -- builder to use; default is html -A -- pass a value into the templates, for HTML builder -N -- do not do colored output -q -- no output on stdout, just warnings on stderr + -Q -- no output at all, not even warnings -P -- run Pdb on exception Modi: * without -a and without filenames, write new and changed files. @@ -89,6 +90,7 @@ def main(argv=sys.argv): buildername = all_files = None freshenv = use_pdb = False status = sys.stdout + warning = sys.stderr confoverrides = {} htmlcontext = {} doctreedir = path.join(outdir, '.doctrees') @@ -138,13 +140,16 @@ def main(argv=sys.argv): freshenv = True elif opt == '-q': status = StringIO() + elif opt == '-Q': + status = StringIO() + warning = StringIO() elif opt == '-P': use_pdb = True confoverrides['html_context'] = htmlcontext try: app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername, - confoverrides, status, sys.stderr, freshenv) + confoverrides, status, warning, freshenv) app.build(all_files, filenames) except KeyboardInterrupt: if use_pdb: From a41c0ee86c3a412465c50151f2cf309e825d632a Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 4 Nov 2008 08:46:28 +0100 Subject: [PATCH 08/12] Document -A and -Q switches. --- CHANGES | 5 +++++ doc/intro.rst | 8 ++++++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/CHANGES b/CHANGES index d753c40273..a375f0d760 100644 --- a/CHANGES +++ b/CHANGES @@ -122,6 +122,11 @@ New features added * Other changes: + - Added a command-line switch ``-Q``: it will suppress warnings. + + - Added a command-line switch ``-A``: it can be used to give additional + values into the HTML templates. + - Added a distutils command `build_sphinx`: When Sphinx is installed, you can call ``python setup.py build_sphinx`` for projects that have Sphinx documentation, which will build the docs and place them in diff --git a/doc/intro.rst b/doc/intro.rst index de288dbde4..34f791ed9c 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -114,8 +114,12 @@ The :program:`sphinx-build` script has several more options: case.) **-q** - Do not output anything on standard output, only write warnings to standard - error. + Do not output anything on standard output, only write warnings and errors to + standard error. + +**-Q** + Do not output anything on standard output, also suppress warnings. Only + errors are written to standard error. **-P** (Useful for debugging only.) Run the Python debugger, :mod:`pdb`, if an From 78b1f6e613488c481f53d921d664a94420878980 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 4 Nov 2008 19:51:23 +0100 Subject: [PATCH 09/12] Doc tweaks. --- CHANGES | 4 ++-- doc/intro.rst | 3 +++ 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/CHANGES b/CHANGES index a375f0d760..590ea70675 100644 --- a/CHANGES +++ b/CHANGES @@ -124,8 +124,8 @@ New features added - Added a command-line switch ``-Q``: it will suppress warnings. - - Added a command-line switch ``-A``: it can be used to give additional - values into the HTML templates. + - Added a command-line switch ``-A``: it can be used to supply + additional values into the HTML templates. - Added a distutils command `build_sphinx`: When Sphinx is installed, you can call ``python setup.py build_sphinx`` for projects that have diff --git a/doc/intro.rst b/doc/intro.rst index 34f791ed9c..af3cc1aaab 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -109,6 +109,9 @@ The :program:`sphinx-build` script has several more options: Override a configuration value set in the :file:`conf.py` file. (The value must be a string value.) +**-A** *name=value* + Make the *name* assigned to *value* in the HTML templates. + **-N** Do not do colored output. (On Windows, colored output is disabled in any case.) From dc5e1a159d6ea83d14de13daf1dbf40b8c4f31f9 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 4 Nov 2008 19:51:38 +0100 Subject: [PATCH 10/12] Use * instead of *.* as glob pattern, catches Makefile. --- MANIFEST.in | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/MANIFEST.in b/MANIFEST.in index c468330d4a..d87a881efa 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -11,12 +11,12 @@ include ez_setup.py include sphinx-build.py include sphinx-quickstart.py -recursive-include sphinx/texinputs *.* +recursive-include sphinx/texinputs * recursive-include sphinx/templates *.html *.xml -recursive-include sphinx/static *.* -recursive-include sphinx/locale *.* -recursive-include tests *.* -recursive-include utils *.* +recursive-include sphinx/static * +recursive-include sphinx/locale * +recursive-include tests * +recursive-include utils * -recursive-include doc *.* +recursive-include doc * prune doc/_build From a29cd9518ae15a4fd370b01554d70980abe96f7e Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 4 Nov 2008 21:11:11 +0100 Subject: [PATCH 11/12] Add Director. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index 85d85a88ce..ea0274c750 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -24,6 +24,7 @@ to be included, please mail to `the Google group * Satchmo: http://www.satchmoproject.com/docs/svn/ * PyEphem: http://rhodesmill.org/pyephem/ * Paste: http://pythonpaste.org/script/ +* Director: http://packages.python.org/director/ * Calibre: http://calibre.kovidgoyal.net/user_manual/ * PyUblas: http://tiker.net/doc/pyublas/ * Py on Windows: http://timgolden.me.uk/python-on-windows/ From 7aa1c5eed298cfbfa6638ac2cd6f53fe1d75bdc0 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 4 Nov 2008 21:35:05 +0100 Subject: [PATCH 12/12] #21: allow short form for seealso arguments. --- CHANGES | 3 +++ doc/markup/para.rst | 7 +++++++ sphinx/directives/other.py | 11 ++++++++--- sphinx/util/compat.py | 2 +- tests/root/markup.txt | 2 +- 5 files changed, 20 insertions(+), 5 deletions(-) diff --git a/CHANGES b/CHANGES index 590ea70675..e1fd96a2b2 100644 --- a/CHANGES +++ b/CHANGES @@ -28,6 +28,9 @@ New features added - Lists enumerated by letters or roman numerals are now handled like in standard reST. + - The ``seealso`` directive can now also be given arguments, as a short + form. + * HTML output and templates: - Incompatible change: The "root" relation link (top left in the diff --git a/doc/markup/para.rst b/doc/markup/para.rst index ebc70426e3..c60eb25876 100644 --- a/doc/markup/para.rst +++ b/doc/markup/para.rst @@ -74,6 +74,13 @@ units as well as normal text: `GNU tar manual, Basic Tar Format `_ Documentation for tar archive files, including GNU tar extensions. + There's also a "short form" allowed that looks like this:: + + .. seealso:: modules :mod:`zipfile`, :mod:`tarfile` + + .. versionadded:: 0.5 + The short form. + .. directive:: .. rubric:: title This directive creates a paragraph heading that is not used to create a diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index 442313a93f..2e64eb0cfa 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -229,13 +229,18 @@ directives.register_directive('versionchanged', version_directive) def seealso_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): - rv = make_admonition( + seealsonode = make_admonition( addnodes.seealso, name, [_('See also')], options, content, lineno, content_offset, block_text, state, state_machine) - return rv + if arguments: + argnodes, msgs = state.inline_text(arguments[0], lineno) + para = nodes.paragraph() + para += argnodes + seealsonode[1:1] = [para] + msgs + return [seealsonode] seealso_directive.content = 1 -seealso_directive.arguments = (0, 0, 0) +seealso_directive.arguments = (0, 1, 1) directives.register_directive('seealso', seealso_directive) diff --git a/sphinx/util/compat.py b/sphinx/util/compat.py index f7d646b6cc..f9b88a4490 100644 --- a/sphinx/util/compat.py +++ b/sphinx/util/compat.py @@ -33,5 +33,5 @@ def make_admonition(node_class, name, arguments, options, content, lineno, classes = ['admonition-' + nodes.make_id(title_text)] admonition_node['classes'] += classes state.nested_parse(content, content_offset, admonition_node) - return [admonition_node] + return admonition_node diff --git a/tests/root/markup.txt b/tests/root/markup.txt index 43e4e59028..c2c6b7440b 100644 --- a/tests/root/markup.txt +++ b/tests/root/markup.txt @@ -99,7 +99,7 @@ Stuff [#]_ Reference lookup: [Ref1]_ (defined in another file). -.. seealso:: +.. seealso:: something, something else, something more `Google `_ For everything.