Commits

Michael Forbes committed 19f3c79 Merge

Pulling in original sphinx branch.

Comments (0)

Files changed (23)

 6d93c72d97d9e3cc7d2f3c03f279af0c7b1e85ff 0.1.61798
 17af190a72e157f767e30a284f49bdcd2b5a3689 0.1.61611
 24a2061063212f1951507a35ed589a55cd9dd962 0.6.4
+f76fb0be8011dbecec8f39fba791feca24351bfb 0.6.5
 Release 1.0 (in development)
 ============================
 
+* Sphinx now requires Jinja2 version 2.2 or greater.
+
 * Added ``needs_sphinx`` config value and ``Sphinx.require_sphinx``
   application API function.
 
 * Added single-file HTML builder.
 
+* Added ``autodoc_default_flags`` config value, which can be used
+  to select default flags for all autodoc directives.
+
 * Added ``tab-width`` option to ``literalinclude`` directive.
 
 * The ``html_sidebars`` config value can now contain patterns as
 * Added ``htmltitle`` block in layout template.
 
 
-Release 0.6.5 (in development)
+Release 0.6.6 (in development)
 ==============================
 
+
+Release 0.6.5 (Mar 01, 2010)
+============================
+
+* In autodoc, fix the omission of some module members explicitly
+  documented using documentation comments.
+
+* #345: Fix cropping of sidebar scroll bar with ``stickysidebar``
+  option of the default theme.
+
+* #341: Always generate UNIX newlines in the quickstart Makefile.
+
+* #338: Fix running with ``-C`` under Windows.
+
+* In autodoc, allow customizing the signature of an object where
+  the built-in mechanism fails.
+
+* #331: Fix output for enumerated lists with start values in LaTeX.
+
 * Make the ``start-after`` and ``end-before`` options to the
   ``literalinclude`` directive work correctly if not used together.
 
    details about it.  For definition of the epub format, have a look at
    `<http://www.idpf.org/specs.htm>`_ or `<http://en.wikipedia.org/wiki/EPUB>`_.
 
+   Some ebook readers do not show the link targets of references.  Therefore
+   this builder adds the targets after the link when necessary.  The display
+   of the URLs can be customized by adding CSS rules for the class
+   ``link-target``.
+
    Its name is ``epub``.
 
 .. module:: sphinx.builders.latex
 
 .. confval:: pygments_style
 
-   The style name to use for Pygments highlighting of source code.  Default is
-   ``'sphinx'``, which is a builtin style designed to match Sphinx' default
-   style.
+   The style name to use for Pygments highlighting of source code.  The default
+   style is selected by the theme for HTML output, and ``'sphinx'`` otherwise.
 
    .. versionchanged:: 0.3
       If the value is a fully-qualified name of a custom Pygments style class,
    A list of files that are generated/copied in the build directory but should
    not be included in the epub file.  The default value is ``[]``.
 
+.. confval:: epub_tocdepth
+
+   The depth of the table of contents in the file :file:`toc.ncx`.  It should
+   be an integer greater than zero.  The default value is 3.  Note: A deeply
+   nested table of contents may be difficult to navigate.
+
 
 .. _latex-options:
 

doc/ext/autodoc.rst

 
    .. versionadded:: 0.6
 
+.. confval:: autodoc_default_flags
+
+   This value is a list of autodoc directive flags that should be automatically
+   applied to all autodoc directives.  The supported flags are ``'members'``,
+   ``'undoc-members'``, ``'inherited-members'`` and ``'show-inheritance'``.
+
+   If you set one of these flags in this config value, you can use a negated
+   form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once.
+   For example, if ``autodoc_default_flags`` is set to ``['members',
+   'undoc-members']``, and you write a directive like this::
+
+      .. automodule:: foo
+         :no-undoc-members:
+
+   the directive will be interpreted as if only ``:members:`` was given.
+
+   .. versionadded:: 1.0
+
 
 Docstring preprocessing
 -----------------------

doc/ext/autosummary.rst

      :confval:`templates_path` to generate the pages for all entries
      listed. See `Customizing templates`_ below.
 
+     .. versionadded:: 1.0
+
 
 :program:`sphinx-autogen` -- generate autodoc stub pages
 --------------------------------------------------------
 Customizing templates
 ---------------------
 
+.. versionadded:: 1.0
+
 You can customize the stub page templates, in a similar way as the HTML Jinja
 templates, see :ref:`templating`. (:class:`~sphinx.application.TemplateBridge`
 is not supported.)

doc/templating.rst

 .. data:: toctree
 
    A callable yielding the global TOC tree containing the current page, rendered
-   as HTML bullet lists.  If the optional keyword argument ``collapse`` is true,
-   all TOC entries that are not ancestors of the current page are collapsed.
+   as HTML bullet lists.  If the optional keyword argument ``collapse`` is true
+   (the default), all TOC entries that are not ancestors of the current page are
+   collapsed.
     headings.
   - **headerlinkcolor** (CSS color): Color for the backreference link in
     headings.
+  - **textalign** (CSS *text-align* value): Text alignment for the body, default
+    is ``justify``.
 
 * **nature** -- A greenish theme.  There are currently no options beyond
   *nosidebar*.
 <http://bitbucket.org/birkenfeld/sphinx/get/tip.gz#egg=Sphinx-dev>`_.
 '''
 
-requires = ['Pygments>=0.8', 'Jinja2>=2.1', 'docutils>=0.4']
+requires = ['Pygments>=0.8', 'Jinja2>=2.2', 'docutils>=0.4']
 
 if sys.version_info < (2, 4):
     print 'ERROR: Sphinx requires at least Python 2.4 to run.'

File contents unchanged.

sphinx/application.py

         self.config = Config(confdir, CONFIG_FILENAME, confoverrides, self.tags)
         self.config.check_unicode(self.warn)
 
+        # set confdir to srcdir if -C given (!= no confdir); a few pieces
+        # of code expect a confdir to be set
+        if self.confdir is None:
+            self.confdir = self.srcdir
+
         # load all extension modules
         for extension in self.config.extensions:
             self.setup_extension(extension)

sphinx/builders/epub.py

 import zipfile
 
 from docutils import nodes
+from docutils.transforms import Transform
 
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.util.osutil import EEXIST
 
 # (Fragment) templates from which the metainfo files content.opf, toc.ncx,
 # mimetype, and META-INF/container.xml are created.
+# This template section also defines strings that are embedded in the html
+# output but that may be customized by (re-)setting module attributes,
+# e.g. from conf.py.
 
 _mimetype_template = 'application/epub+zip' # no EOL!
 
 
 _toctree_template = u'toctree-l%d'
 
+_link_target_template = u' [%(uri)s]'
+
+_css_link_target_class = u'link-target'
+
 _media_types = {
     '.html': 'application/xhtml+xml',
     '.css': 'text/css',
 }
 
 
+# The transform to show link targets
+
+class VisibleLinksTransform(Transform):
+    """
+    Add the link target of referances to the text, unless it is already
+    present in the description.
+    """
+
+    # This transform must run after the references transforms
+    default_priority = 680
+
+    def apply(self):
+        for ref in self.document.traverse(nodes.reference):
+            uri = ref.get('refuri', '')
+            if ( uri.startswith('http:') or uri.startswith('https:') or \
+                    uri.startswith('ftp:') ) and uri not in ref.astext():
+                uri = _link_target_template % {'uri': uri}
+                if uri:
+                    idx = ref.parent.index(ref) + 1
+                    link = nodes.inline(uri, uri)
+                    link['classes'].append(_css_link_target_class)
+                    ref.parent.insert(idx, link)
+
+
 # The epub publisher
 
 class EpubBuilder(StandaloneHTMLBuilder):
         # the output files for epub must be .html only
         self.out_suffix = '.html'
         self.playorder = 0
+        self.app.add_transform(VisibleLinksTransform)
 
     def get_theme_config(self):
         return self.config.epub_theme, {}
     # generic support functions
     def make_id(self, name):
         """Replace all characters not allowed for (X)HTML ids."""
-        return name.replace('/', '_')
+        return name.replace('/', '_').replace(' ', '')
 
     def esc(self, name):
         """Replace all characters not allowed in text an attribute values."""
         name = name.replace('\'', '&apos;')
         return name
 
-    def collapse_text(self, doctree, result):
-       """Remove all HTML markup and return only the text nodes."""
-       for c in doctree.children:
-            if isinstance(c, nodes.Text):
-                try:
-                    # docutils 0.4 and 0.5: Text is a UserString subclass
-                    result.append(c.data)
-                except AttributeError:
-                    # docutils 0.6: Text is a unicode subclass
-                    result.append(c)
-            else:
-                result = self.collapse_text(c, result)
-       return result
-
     def get_refnodes(self, doctree, result):
         """Collect section titles, their depth in the toc and the refuri."""
         # XXX: is there a better way than checking the attribute
-        # toctree-l[1-6] on the parent node?
+        # toctree-l[1-8] on the parent node?
         if isinstance(doctree, nodes.reference):
             classes = doctree.parent.attributes['classes']
             level = 1
-            for l in range(5,0,-1): # or range(1,6)?
+            for l in range(8, 0, -1): # or range(1, 8)?
                 if (_toctree_template % l) in classes:
                     level = l
             result.append({
                 'level': level,
                 'refuri': self.esc(doctree['refuri']),
-                'text': self.esc(''.join(self.collapse_text(doctree, [])))
+                'text': self.esc(doctree.astext())
             })
         else:
             for elem in doctree.children:
         """Get the total table of contents, containg the master_doc
         and pre and post files not managed by sphinx.
         """
-        doctree = self.env.get_and_resolve_doctree(self.config.master_doc, self)
+        doctree = self.env.get_and_resolve_doctree(self.config.master_doc,
+            self, prune_toctrees=False)
         self.refnodes = self.get_refnodes(doctree, [])
         self.refnodes.insert(0, {
             'level': 1,
             'refuri': self.esc(self.config.master_doc + '.html'),
-            'text': self.esc(''.join(self.collapse_text(
-                self.env.titles[self.config.master_doc], []
-            ))),
+            'text': self.esc(self.env.titles[self.config.master_doc].astext())
         })
-        # XXX: is reversed ok?
         for file, text in reversed(self.config.epub_pre_files):
             self.refnodes.insert(0, {
                 'level': 1,
             for fn in files:
                 filename = path.join(root, fn)[olen:]
                 if filename in self.ignored_files:
-                    # self.warn("ignoring %s" % filename)
                     continue
                 ext = path.splitext(filename)[-1]
                 if ext not in _media_types:
-                    self.warn("unknown mimetype for %s, ignoring" % filename)
+                    self.warn('unknown mimetype for %s, ignoring' % filename)
                     continue
                 projectfiles.append(_file_template % {
                     'href': self.esc(filename),
         """Insert nested navpoints for given node.
         The node and subnav are already rendered to text.
         """
-        nlist = node.split('\n')
+        nlist = node.rsplit('\n', 1)
         nlist.insert(-1, subnav)
         return '\n'.join(nlist)
 
             file = node['refuri'].split('#')[0]
             if file in self.ignored_files:
                 continue
+            if node['level'] > self.config.epub_tocdepth:
+                continue
             if node['level'] == level:
-                navlist.append(self.new_navpoint(node,level))
+                navlist.append(self.new_navpoint(node, level))
             elif node['level'] == level + 1:
                 navstack.append(navlist)
                 navlist = []
 
         navpoints = self.build_navpoints(self.refnodes)
         level = max(item['level'] for item in self.refnodes)
+        level = min(level, self.config.epub_tocdepth)
         f = codecs.open(path.join(outdir, outname), 'w', 'utf-8')
         try:
             f.write(_toc_template % self.toc_metadata(level, navpoints))
         epub_pre_files = ([], 'env'),
         epub_post_files = ([], 'env'),
         epub_exclude_files = ([], 'env'),
+        epub_tocdepth = (3, 'env'),
 
         # LaTeX options
         latex_documents = ([], None),

sphinx/environment.py

         self.note_citations_from(docname, doctree)
         self.build_toc_from(docname, doctree)
 
-        # store time of reading, used to find outdated files
+        # store time of build, for outdated files detection
         self.all_docs[docname] = time.time()
 
         if app:
         else:
             if name in self.descrefs:
                 newname = name
+            elif classname and classname + '.' + name in self.descrefs:
+                newname = classname + '.' + name
             elif modname and modname + '.' + name in self.descrefs:
                 newname = modname + '.' + name
             elif modname and classname and \

sphinx/ext/autodoc.py

             args = "(%s)" % self.args
         else:
             # try to introspect the signature
-            args = self.format_args()
+            try:
+                args = self.format_args()
+            except Exception, err:
+                self.directive.warn('error while formatting arguments for '
+                                    '%s: %s' % (self.fullname, err))
+                args = None
 
         retann = self.retann
 
             # of inner classes can be documented
             full_mname = self.modname + '::' + \
                               '.'.join(self.objpath + [mname])
-            memberdocumenters.append(
-                classes[-1](self.directive, full_mname, self.indent))
+            documenter = classes[-1](self.directive, full_mname, self.indent)
+            memberdocumenters.append((documenter, isattr))
 
         if (self.options.member_order or self.env.config.autodoc_member_order) \
                == 'groupwise':
             # sort by group; relies on stable sort to keep items in the
             # same group sorted alphabetically
-            memberdocumenters.sort(key=lambda d: d.member_order)
+            memberdocumenters.sort(key=lambda d: d[0].member_order)
 
-        for documenter in memberdocumenters:
-            documenter.generate(all_members=True,
-                                real_modname=self.real_modname,
-                                check_module=members_check_module)
+        for documenter, isattr in memberdocumenters:
+            documenter.generate(
+                all_members=True, real_modname=self.real_modname,
+                check_module=members_check_module and not isattr)
 
         # reset current objects
         self.env.autodoc_current_module = None
         self.add_line(u'', '')
 
         # format the object's signature, if any
-        try:
-            sig = self.format_signature()
-        except Exception, err:
-            self.directive.warn('error while formatting signature for '
-                                '%s: %s' % (self.fullname, err))
-            sig = ''
+        sig = self.format_signature()
 
         # generate the directive header and options, if applicable
         self.add_directive_header(sig)
         return ret
 
     def format_args(self):
-        args = None
         # for classes, the relevant signature is the __init__ method's
         initmeth = self.get_attr(self.object, '__init__', None)
         # classes without __init__ method, default __init__ or
     # a registry of type -> getattr function
     _special_attrgetters = {}
 
+    # flags that can be given in autodoc_default_flags
+    _default_flags = set(['members', 'undoc-members', 'inherited-members',
+                          'show-inheritance'])
+
     # standard docutils directive settings
     has_content = True
     required_arguments = 1
         # find out what documenter to call
         objtype = self.name[4:]
         doc_class = self._registry[objtype]
+        # add default flags
+        for flag in self._default_flags:
+            if flag not in doc_class.option_spec:
+                continue
+            negated = self.options.pop('no-' + flag, 'not given') is None
+            if flag in self.env.config.autodoc_default_flags and \
+               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))
 
     app.add_config_value('autoclass_content', 'class', True)
     app.add_config_value('autodoc_member_order', 'alphabetic', True)
+    app.add_config_value('autodoc_default_flags', [], True)
     app.add_event('autodoc-process-docstring')
     app.add_event('autodoc-process-signature')
     app.add_event('autodoc-skip-member')

sphinx/quickstart.py

 
 # A list of files that should not be packed into the epub file.
 #epub_exclude_files = []
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
 '''
 
 INTERSPHINX_CONFIG = '''
 
 REM Command file for Sphinx documentation
 
-set SPHINXBUILD=sphinx-build
+if "%%SPHINXBUILD%%" == "" (
+\tset SPHINXBUILD=sphinx-build
+)
 set BUILDDIR=%(rbuilddir)s
 set ALLSPHINXOPTS=-d %%BUILDDIR%%/doctrees %%SPHINXOPTS%% %(rsrcdir)s
 if NOT "%%PAPER%%" == "" (
     if d['makefile']:
         d['rsrcdir'] = d['sep'] and 'source' or '.'
         d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
-        f = open(path.join(d['path'], 'Makefile'), 'w')
+        # use binary mode, to avoid writing \r\n on Windows
+        f = open(path.join(d['path'], 'Makefile'), 'wb')
         f.write((MAKEFILE % d).encode('utf-8'))
         f.close()
 

sphinx/setup_command.py

 
 
 class BuildDoc(Command):
-    """Distutils command to build Sphinx documentation."""
+    """Distutils command to build Sphinx documentation.
+
+    The Sphinx build can then be triggered from distutils, and some Sphinx
+    options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx own
+    configuration file.
+
+    For instance, from `setup.py`::
+
+       # this is only necessary when not using setuptools/distribute
+       from sphinx.setup_command import BuildDoc
+       cmdclass = {'build_sphinx': BuildDoc}
+
+       name = 'My project'
+       version = 1.2
+       release = 1.2.0
+       setup(
+           name=name,
+           author='Bernard Montgomery',
+           version=release,
+           cmdclass={'build_sphinx': BuildDoc},
+           # these are optional and override conf.py settings
+           command_options={
+               'build_sphinx': {
+                   'project': ('setup.py', name),
+                   'version': ('setup.py', version),
+                   'release': ('setup.py', release)}},
+       )
+
+    Or add this section in ``setup.cfg``::
+
+       [build_sphinx]
+       project = 'My project'
+       version = 1.2
+       release = 1.2.0
+    """
 
     description = 'Build Sphinx documentation'
     user_options = [
         ('source-dir=', 's', 'Source directory'),
         ('build-dir=', None, 'Build directory'),
         ('builder=', 'b', 'The builder to use. Defaults to "html"'),
-        ]
+        ('project=', None, 'The documented project\'s name'),
+        ('version=', None, 'The short X.Y version'),
+        ('release=', None, 'The full version, including alpha/beta/rc tags'),
+        ('today=', None, 'How to format the current date, used as the '
+         'replacement for |today|'),
+    ]
     boolean_options = ['fresh-env', 'all-files']
 
 
     def initialize_options(self):
         self.fresh_env = self.all_files = False
         self.source_dir = self.build_dir = None
-        self.conf_file_name = 'conf.py'
         self.builder = 'html'
+        self.version = ''
+        self.release = ''
+        self.today = ''
 
     def _guess_source_dir(self):
         for guess in ('doc', 'docs'):
             status_stream = StringIO()
         else:
             status_stream = sys.stdout
+        confoverrides = {}
+        if self.version:
+             confoverrides['version'] = self.version
+        if self.release:
+             confoverrides['release'] = self.release
+        if self.today:
+             confoverrides['today'] = self.today
         app = Sphinx(self.source_dir, self.source_dir,
                      self.builder_target_dir, self.doctree_dir,
-                     self.builder, {}, status_stream,
+                     self.builder, confoverrides, status_stream,
                      freshenv=self.fresh_env)
 
         try:

sphinx/themes/agogo/static/agogo.css_t

 
 /* Default body styles */
 a {
-  text-decoration: none;
   color: {{ theme_linkcolor }};
 }
 
+div.bodywrapper a, div.footer a {
+  text-decoration: underline;
+}
+
 .clearer {
   clear: both;
 }
   visibility: visible;
 }
 
+img {
+  border: 0;
+}
 
+div.admonition {
+  margin-top: 10px;
+  margin-bottom: 10px;
+  padding: 2px 7px 1px 7px;
+  border-left: 0.2em solid black;
+}
+
+p.admonition-title {
+  margin: 0px 10px 5px 0px;
+  font-weight: bold;
+}
 
 /* Header */
 
 
 div.body {
   padding-right: 2em;
-  text-align: justify;
+  text-align: {{ theme_textalign }};
 }
 
 div.document ul {
   font-size: .9em;
 }
 
+div.sidebar a, div.header a {
+  text-decoration: none;
+}
+
+div.sidebar a:hover, div.header a:hover {
+  text-decoration: underline;
+}
+
 div.sidebar h3 {
   color: #2e3436;
   text-transform: uppercase;
 div.sidebar li.toctree-l2 a {
   background-color: transparent;
   border: none;
+  margin-left: 1em;
+  border-bottom: 1px solid #dddddd;
+}
+
+div.sidebar li.toctree-l3 a {
+  background-color: transparent;
+  border: none;
+  margin-left: 2em;
   border-bottom: 1px solid #dddddd;
 }
 

sphinx/themes/agogo/theme.conf

 linkcolor = #ce5c00
 headercolor1 = #204a87
 headercolor2 = #3465a4
-headerlinkcolor = #fcaf3e
+headerlinkcolor = #fcaf3e
+textalign = justify

sphinx/themes/default/static/default.css_t

 div.sphinxsidebar {
     {%- if theme_stickysidebar|tobool %}
     top: 30px;
+    bottom: 0;
     margin: 0;
     position: fixed;
     overflow: auto;
-    height: 100%;
+    height: auto;
     {%- endif %}
     {%- if theme_rightsidebar|tobool %}
     float: right;

sphinx/themes/epub/static/epub.css

     text-decoration: underline;
 }
 
+/* -- link-target ----------------------------------------------------------- */
+
+.link-target {
+    font-size: 80%;
+}
+
+table .link-target {
+    /* Do not show links in tables, there is not enough space */
+    display: none;
+}
+
+/* -- font-face ------------------------------------------------------------- */
+
 @font-face {
     font-family: "LiberationNarrow";
     font-style: normal;

sphinx/writers/latex.py

 
     def visit_enumerated_list(self, node):
         self.body.append('\\begin{enumerate}\n' )
+        if 'start' in node:
+            self.body.append('\\setcounter{enumi}{%d}\n' % (node['start'] - 1))
     def depart_enumerated_list(self, node):
         self.body.append('\\end{enumerate}\n' )
 

tests/test_autodoc.py

     assert formatsig('method', 'H.foo', H.foo1, 'a', None) == '(a)'
     assert formatsig('method', 'H.foo', H.foo2, None, None) == '(b, *c)'
 
-    # test exception handling
-    raises(TypeError, formatsig, 'function', 'int', int, None, None)
+    # test exception handling (exception is caught and args is '')
+    assert formatsig('function', 'int', int, None, None) == ''
+    del _warnings[:]
 
     # test processing by event handler
     assert formatsig('method', 'bar', H.foo1, None, None) == '42'
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.