fixed __init__.py to work with merge

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

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/

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

TODO

@@ -2,5 +2,5 @@ Sphinx TODO
 ===========
 
 All todo items are now tracked as issues in the Sphinx issue tracker at
-<http://code.google.com/p/sphinx/issues/list>.
+<http://www.bitbucket.org/birkenfeld/sphinx/issues/>.
 

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

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

doc/markup/para.rst

@@ -74,6 +74,13 @@ units as well as normal text:
          `GNU tar manual, Basic Tar Format <http://link>`_
             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

sphinx/__init__.py

@@ -39,8 +39,10 @@ Options: -b <builder> -- builder to use; default is html
          -c <path> -- path where configuration file (conf.py) is located
                       (default: same as sourcedir)
          -D <setting=value> -- override a setting in configuration
+         -A <name=value>    -- 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 <path> -- 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:

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))

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),

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

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)
 
 

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
 

tests/root/_templates/layout.html

@@ -0,0 +1,4 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+<meta name="hc" content="{{ hckey }}" />
+{% endblock %}

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'
 

tests/root/markup.txt

@@ -99,7 +99,7 @@ Stuff [#]_
 
 Reference lookup: [Ref1]_ (defined in another file).
 
-.. seealso::
+.. seealso:: something, something else, something more
 
    `Google <http://www.google.com>`_
        For everything.

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]',
     },
 }