diff --git a/CHANGES b/CHANGES index 0ab7bbd239..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 @@ -58,6 +61,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 @@ -119,6 +125,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 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 Sphinx documentation, which will build the docs and place them in 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/ 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 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 -. +. diff --git a/doc/intro.rst b/doc/intro.rst index de288dbde4..af3cc1aaab 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -109,13 +109,20 @@ 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.) **-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 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 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-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 diff --git a/sphinx/__init__.py b/sphinx/__init__.py index bda0efb09d..032531157d 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -39,8 +39,10 @@ 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 + -Q -- no output at all, not even warnings -P -- run Pdb on exception -g -- create autogenerated files Modi: @@ -60,7 +62,7 @@ def main(argv=sys.argv): nocolor() try: - opts, args = getopt.getopt(argv[1:], 'ab:d:c:D:g:NEqP') + opts, args = getopt.getopt(argv[1:], 'ab:d:c:D:A:g:NEqP') srcdir = confdir = path.abspath(args[0]) if not path.isdir(srcdir): print >>sys.stderr, 'Error: Cannot find source directory.' @@ -90,7 +92,9 @@ 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') for opt, val in opts: @@ -120,24 +124,45 @@ 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': 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: diff --git a/sphinx/builder.py b/sphinx/builder.py index d466bd7030..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( @@ -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.""" @@ -558,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)) 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/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 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/_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/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. 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]', }, }