Anonymous avatar Anonymous committed 73e323e

Add module names even to names in classes. Add a config option for that.
Add a :samp: role for highlighting text inside literal code.
Fix the time module docs.

Comments (0)

Files changed (9)

 # Else, today_fmt is used as the format for a strftime call.
 today_fmt = '%B %d, %Y'
 
+# The base URL for download links.
+download_base_url = 'http://docs.python.org/ftp/python/doc/'
+
 # List of files that shouldn't be included in the build.
 unused_files = [
     'whatsnew/2.0.rst',
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
 
-# The base URL for download links.
-download_base_url = 'http://docs.python.org/ftp/python/doc/'
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True

Doc-26/documenting/markup.rst

 
    A regular expression. Quotes should not be included.
 
+.. describe:: samp
+
+   A piece of literal text, such as code.  Within the contents, you can use
+   curly braces to indicate a "variable" part, as in ``:file:``.
+
+   If you don't need the "variable part" indication, use the standard
+   ````code```` instead.   
+
 .. describe:: var
 
    A Python or C variable or parameter name.

Doc-26/library/time.rst

 
       The :envvar:`TZ` environment variable should contain no whitespace.
 
-   The standard format of the :envvar:`TZ` environment variable is: (whitespace
-   added for clarity)
+   The standard format of the :envvar:`TZ` environment variable is (whitespace
+   added for clarity)::
 
-   std offset [dst [offset
-      [,start[/time], end[/time]]]]
+      std offset [dst [offset [,start[/time], end[/time]]]]
 
-   Where:
+   Where the components are:
 
-   std and dst
+   ``std`` and ``dst``
       Three or more alphanumerics giving the timezone abbreviations. These will be
       propagated into time.tzname
 
-   offset
-      The offset has the form: ± hh[:mm[:ss]]. This indicates the value added the
-      local time to arrive at UTC.  If preceded by a '-', the timezone is east of the
-      Prime  Meridian; otherwise, it is west. If no offset follows dst, summer time is
-      assumed to be one hour ahead of standard time.
+   ``offset``
+      The offset has the form: ``± hh[:mm[:ss]]``. This indicates the value
+      added the local time to arrive at UTC.  If preceded by a '-', the timezone
+      is east of the Prime Meridian; otherwise, it is west. If no offset follows
+      dst, summer time is assumed to be one hour ahead of standard time.
 
-   start[/time
-      ,end[/time]] Indicates when to change to and back from DST. The format of the
+   ``start[/time], end[/time]``
+      Indicates when to change to and back from DST. The format of the
       start and end dates are one of the following:
 
-      J*n*
-         The Julian day *n* (1 <= *n* <= 365). Leap days are not  counted, so in all
-         years February 28 is day 59 and March 1 is day 60.
+      :samp:`J{n}`
+         The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in
+         all years February 28 is day 59 and March 1 is day 60.
 
-      *n*
-         The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and it is
-         possible to refer to February 29.
+      :samp:`{n}`
+         The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and
+         it is possible to refer to February 29.
 
-      M*m*.*n*.*d*
-         The *d*'th day (0 <= *d* <= 6) or week *n*  of month *m* of the year (1 <= *n*
-         <= 5,  1 <= *m* <= 12, where week 5 means "the last *d* day in month *m*" which
-         may occur in either the fourth or  the fifth week). Week 1 is the first week in
-         which the  *d*'th day occurs. Day zero is Sunday.
+      :samp:`M{m}.{n}.{d}`
+         The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1
+         <= *n* <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in
+         month *m*" which may occur in either the fourth or the fifth
+         week). Week 1 is the first week in which the *d*'th day occurs. Day
+         zero is Sunday.
 
-      time has the same format as offset except that no leading sign ('-' or '+') is
-      allowed. The default, if time is not given, is 02:00:00.
+      ``time`` has the same format as ``offset`` except that no leading sign
+      ('-' or '+') is allowed. The default, if time is not given, is 02:00:00.
 
    ::
 
 # Else, today_fmt is used as the format for a strftime call.
 today_fmt = '%B %d, %Y'
 
+# The base URL for download links.
+download_base_url = 'http://docs.python.org/ftp/python/doc/'
+
 # List of files that shouldn't be included in the build.
 unused_files = [
     'whatsnew/2.0.rst',
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
 
-# The base URL for download links.
-download_base_url = 'http://docs.python.org/ftp/python/doc/'
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True

Doc-3k/documenting/markup.rst

 
    A regular expression. Quotes should not be included.
 
+.. describe:: samp
+
+   A piece of literal text, such as code.  Within the contents, you can use
+   curly braces to indicate a "variable" part, as in ``:file:``.
+
+   If you don't need the "variable part" indication, use the standard
+   ````code```` instead.   
+
 .. describe:: var
 
    A Python or C variable or parameter name.

Doc-3k/library/time.rst

 
       The :envvar:`TZ` environment variable should contain no whitespace.
 
-   The standard format of the :envvar:`TZ` environment variable is: (whitespace
-   added for clarity)
+   The standard format of the :envvar:`TZ` environment variable is (whitespace
+   added for clarity)::
 
-   std offset [dst [offset
-      [,start[/time], end[/time]]]]
+      std offset [dst [offset [,start[/time], end[/time]]]]
 
-   Where:
+   Where the components are:
 
-   std and dst
+   ``std`` and ``dst``
       Three or more alphanumerics giving the timezone abbreviations. These will be
       propagated into time.tzname
 
-   offset
-      The offset has the form: ± hh[:mm[:ss]]. This indicates the value added the
-      local time to arrive at UTC.  If preceded by a '-', the timezone is east of the
-      Prime  Meridian; otherwise, it is west. If no offset follows dst, summer time is
-      assumed to be one hour ahead of standard time.
+   ``offset``
+      The offset has the form: ``± hh[:mm[:ss]]``. This indicates the value
+      added the local time to arrive at UTC.  If preceded by a '-', the timezone
+      is east of the Prime Meridian; otherwise, it is west. If no offset follows
+      dst, summer time is assumed to be one hour ahead of standard time.
 
-   start[/time
-      ,end[/time]] Indicates when to change to and back from DST. The format of the
+   ``start[/time], end[/time]``
+      Indicates when to change to and back from DST. The format of the
       start and end dates are one of the following:
 
-      J*n*
-         The Julian day *n* (1 <= *n* <= 365). Leap days are not  counted, so in all
-         years February 28 is day 59 and March 1 is day 60.
+      :samp:`J{n}`
+         The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in
+         all years February 28 is day 59 and March 1 is day 60.
 
-      *n*
-         The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and it is
-         possible to refer to February 29.
+      :samp:`{n}`
+         The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and
+         it is possible to refer to February 29.
 
-      M*m*.*n*.*d*
-         The *d*'th day (0 <= *d* <= 6) or week *n*  of month *m* of the year (1 <= *n*
-         <= 5,  1 <= *m* <= 12, where week 5 means "the last *d* day in month *m*" which
-         may occur in either the fourth or  the fifth week). Week 1 is the first week in
-         which the  *d*'th day occurs. Day zero is Sunday.
+      :samp:`M{m}.{n}.{d}`
+         The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1
+         <= *n* <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in
+         month *m*" which may occur in either the fourth or the fifth
+         week). Week 1 is the first week in which the *d*'th day occurs. Day
+         zero is Sunday.
 
-      time has the same format as offset except that no leading sign ('-' or '+') is
-      allowed. The default, if time is not given, is 02:00:00.
+      ``time`` has the same format as ``offset`` except that no leading sign
+      ('-' or '+') is allowed. The default, if time is not given, is 02:00:00.
 
    ::
 

sphinx/directives.py

 
 py_paramlist_re = re.compile(r'([\[\],])')  # split at '[', ']' and ','
 
-def parse_py_signature(signode, sig, desctype, currmodule, currclass):
+def parse_py_signature(signode, sig, desctype, env):
     """
     Transform a python signature into RST nodes.
     Return the fully qualified name of the thing.
     if m is None: raise ValueError
     classname, name, arglist = m.groups()
 
-    if currclass:
-        if classname and classname.startswith(currclass):
+    if env.currclass:
+        if classname and classname.startswith(env.currclass):
             fullname = classname + name
-            classname = classname[len(currclass):].lstrip('.')
+            classname = classname[len(env.currclass):].lstrip('.')
         elif classname:
-            fullname = currclass + '.' + classname + name
+            fullname = env.currclass + '.' + classname + name
         else:
-            fullname = currclass + '.' + name
+            fullname = env.currclass + '.' + name
     else:
         fullname = classname + name if classname else name
 
-    if classname:
-        signode += addnodes.desc_classname(classname, classname)
-    # only add the module name for module globals
     # exceptions are a special case, since they are documented in the
     # 'exceptions' module.
-    elif currmodule and currmodule != 'exceptions':
-        signode += addnodes.desc_classname(currmodule+'.', currmodule+'.')
+    if env.config.get('add_module_names', True) and \
+           env.currmodule and env.currmodule != 'exceptions':
+        nodetext = env.currmodule + '.'
+        if classname:
+            nodetext += classname
+        signode += addnodes.desc_classname(nodetext, nodetext)
+    elif classname:
+        signode += addnodes.desc_classname(classname, classname)
 
     signode += addnodes.desc_name(name, name)
     if not arglist:
         try:
             if desctype in ('function', 'data', 'class', 'exception',
                             'method', 'attribute'):
-                name = parse_py_signature(signode, sig, desctype,
-                                          env.currmodule, env.currclass)
+                name = parse_py_signature(signode, sig, desctype, env)
             elif desctype in ('cfunction', 'cmember', 'cmacro', 'ctype', 'cvar'):
                 name = parse_c_signature(signode, sig, desctype)
             elif desctype == 'opcode':

sphinx/environment.py

                     if newmtime == mtime:
                         continue
                     # check the MD5
-                    with file(path.join(self.srcdir, filename), 'rb') as f:
-                        newmd5 = hashlib.md5(f.read()).digest()
-                    if newmd5 != md5:
-                        changed.append(filename)
+                    #with file(path.join(self.srcdir, filename), 'rb') as f:
+                    #    newmd5 = hashlib.md5(f.read()).digest()
+                    #if newmd5 != md5:
+                    changed.append(filename)
 
         return removed, changed
 
         rawtext, utils.unescape(text).replace('-->', u'\N{TRIANGULAR BULLET}'))], []
 
 
-_filevar_re = re.compile('{([^}]+)}')
+_litvar_re = re.compile('{([^}]+)}')
 
-def file_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
+def emph_literal_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
     text = utils.unescape(text)
     retnodes = []
     pos = 0
-    for m in _filevar_re.finditer(text):
+    for m in _litvar_re.finditer(text):
         if m.start() > pos:
             txt = text[pos:m.start()]
             retnodes.append(nodes.literal(txt, txt))
     'token' : xfileref_role,
 
     'menuselection' : menusel_role,
-    'file' : file_role,
+    'file' : emph_literal_role,
+    'samp' : emph_literal_role,
 }
 
 for rolename, func in specific_docroles.iteritems():
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.