Merged in shimizukawa/sphinx-py3-native (pull request #243)

native py2/py3 support without 2to3. refs #1350

4 files changed, 25 insertions, 3 deletions

diff --git a/CHANGES b/CHANGES
index e341afcd..51462260 100644
--- a/CHANGES
+++ b/CHANGES
@@ -35,6 +35,8 @@ New features
 * Prompt for the document language in sphinx-quickstart.
 * PR#217: Added config values to suppress UUID and location information in
   generated gettext catalogs.
+* PR#236, #1456: apidoc: Add a -M option to put module documentation before
+  submodule documentation. Thanks to Wes Turner and Luc Saffre.
 
 Bugs fixed
 ----------
@@ -139,10 +141,13 @@ Bugs fixed
 * #1419: Generated i18n sphinx.js files are missing message catalog entries
   from '.js_t' and '.html'. The issue was introduced in Sphinx 1.1.
 * #636: Keep straight single quotes in literal blocks in the LaTeX build.
+* PR#235: comment db schema of websupport lacked a length of the node_id field.
+  Thanks to solos.
 
 Documentation
 -------------
 
+* Add clarification about the syntax of tags. (:file:`doc/markup/misc.rst`)
 * #1325: Added a "Intersphinx" tutorial section. (:file:`doc/tutorial.rst`)
 * Extended the :ref:`documentation about building extensions <dev-extensions>`.
 
diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst
index b2e9051f..2b069601 100644
--- a/doc/markup/misc.rst
+++ b/doc/markup/misc.rst
@@ -189,6 +189,14 @@ Including content based on tags
    These standard tags are set *after* the configuration file is read, so they
    are not available there.
 
+   All tags must follow the standard Python identifier syntax as set out in
+   the `Identifiers and keywords
+   <https://docs.python.org/reference/lexical_analysis.html#identifiers>`_
+   documentation.  That is, a tag expression may only consist of tags that
+   conform to the syntax of Python variables.  In ASCII, this consists of the
+   uppercase and lowercase letters ``A`` through ``Z``, the underscore ``_``
+   and, except for the first character, the digits ``0`` through ``9``.
+
    .. versionadded:: 0.6
    .. versionchanged:: 1.2
       Added the name of the builder and the prefixes.
diff --git a/sphinx/apidoc.py b/sphinx/apidoc.py
index 346956d3..874fe4b2 100644
--- a/sphinx/apidoc.py
+++ b/sphinx/apidoc.py
@@ -96,6 +96,10 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs):
     """Build the text of the file and write the file."""
     text = format_heading(1, '%s package' % makename(master_package, subroot))
 
+    if opts.modulefirst:
+        text += format_directive(subroot, master_package)
+        text += '\n'
+
     # build a list of directories that are szvpackages (contain an INITPY file)
     subs = [sub for sub in subs if path.isfile(path.join(root, sub, INITPY))]
     # if there are some package directories, add a TOC for theses subpackages
@@ -135,8 +139,9 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs):
                 text += '\n'
         text += '\n'
 
-    text += format_heading(2, 'Module contents')
-    text += format_directive(subroot, master_package)
+    if not opts.modulefirst:
+        text += format_heading(2, 'Module contents')
+        text += format_directive(subroot, master_package)
 
     write_file(makename(master_package, subroot), text, opts)
 
@@ -288,6 +293,10 @@ Note: By default this script will not overwrite already created files.""")
                       help='Don\'t create headings for the module/package '
                            'packages (e.g. when the docstrings already contain '
                            'them)')
+    parser.add_option('-M', '--module-first', action='store_true',
+                      dest='modulefirst',
+                      help='Put module documentation before submodule '
+                      'documentation')
     parser.add_option('-s', '--suffix', action='store', dest='suffix',
                       help='file suffix (default: rst)', default='rst')
     parser.add_option('-F', '--full', action='store_true', dest='full',
diff --git a/sphinx/websupport/storage/sqlalchemy_db.py b/sphinx/websupport/storage/sqlalchemy_db.py
index 7baf8830..afabeade 100644
--- a/sphinx/websupport/storage/sqlalchemy_db.py
+++ b/sphinx/websupport/storage/sqlalchemy_db.py
@@ -131,7 +131,7 @@ class Comment(Base):
     proposal_diff = Column(Text)
     path = Column(String(256), index=True)
 
-    node_id = Column(String, ForeignKey(db_prefix + 'nodes.id'))
+    node_id = Column(String(32), ForeignKey(db_prefix + 'nodes.id'))
     node = relation(Node, backref="comments")
 
     votes = relation(CommentVote, backref="comment",