[Python-checkins] r56769 - in doctools/trunk: Doc-26/conf.py Doc-26/documenting/markup.rst Doc-26/library/time.rst Doc-3k/conf.py Doc-3k/documenting/markup.rst Doc-3k/library/time.rst sphinx/directives.py sphinx/environment.py sphinx/roles.py
georg.brandl
python-checkins at python.org
Mon Aug 6 12:49:53 CEST 2007
Author: georg.brandl
Date: Mon Aug 6 12:49:52 2007
New Revision: 56769
Modified:
doctools/trunk/Doc-26/conf.py
doctools/trunk/Doc-26/documenting/markup.rst
doctools/trunk/Doc-26/library/time.rst
doctools/trunk/Doc-3k/conf.py
doctools/trunk/Doc-3k/documenting/markup.rst
doctools/trunk/Doc-3k/library/time.rst
doctools/trunk/sphinx/directives.py
doctools/trunk/sphinx/environment.py
doctools/trunk/sphinx/roles.py
Log:
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.
Modified: doctools/trunk/Doc-26/conf.py
==============================================================================
--- doctools/trunk/Doc-26/conf.py (original)
+++ doctools/trunk/Doc-26/conf.py Mon Aug 6 12:49:52 2007
@@ -23,6 +23,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',
@@ -47,5 +50,6 @@
# 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
Modified: doctools/trunk/Doc-26/documenting/markup.rst
==============================================================================
--- doctools/trunk/Doc-26/documenting/markup.rst (original)
+++ doctools/trunk/Doc-26/documenting/markup.rst Mon Aug 6 12:49:52 2007
@@ -474,6 +474,14 @@
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.
Modified: doctools/trunk/Doc-26/library/time.rst
==============================================================================
--- doctools/trunk/Doc-26/library/time.rst (original)
+++ doctools/trunk/Doc-26/library/time.rst Mon Aug 6 12:49:52 2007
@@ -445,44 +445,44 @@
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.
-
- *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:`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:`{n}`
+ The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and
+ it is possible to refer to February 29.
+
+ :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.
::
Modified: doctools/trunk/Doc-3k/conf.py
==============================================================================
--- doctools/trunk/Doc-3k/conf.py (original)
+++ doctools/trunk/Doc-3k/conf.py Mon Aug 6 12:49:52 2007
@@ -23,6 +23,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',
@@ -48,5 +51,6 @@
# 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
Modified: doctools/trunk/Doc-3k/documenting/markup.rst
==============================================================================
--- doctools/trunk/Doc-3k/documenting/markup.rst (original)
+++ doctools/trunk/Doc-3k/documenting/markup.rst Mon Aug 6 12:49:52 2007
@@ -474,6 +474,14 @@
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.
Modified: doctools/trunk/Doc-3k/library/time.rst
==============================================================================
--- doctools/trunk/Doc-3k/library/time.rst (original)
+++ doctools/trunk/Doc-3k/library/time.rst Mon Aug 6 12:49:52 2007
@@ -445,44 +445,44 @@
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.
-
- *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:`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:`{n}`
+ The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and
+ it is possible to refer to February 29.
+
+ :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.
::
Modified: doctools/trunk/sphinx/directives.py
==============================================================================
--- doctools/trunk/sphinx/directives.py (original)
+++ doctools/trunk/sphinx/directives.py Mon Aug 6 12:49:52 2007
@@ -113,7 +113,7 @@
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.
@@ -126,24 +126,27 @@
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:
@@ -287,8 +290,7 @@
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':
Modified: doctools/trunk/sphinx/environment.py
==============================================================================
--- doctools/trunk/sphinx/environment.py (original)
+++ doctools/trunk/sphinx/environment.py Mon Aug 6 12:49:52 2007
@@ -281,10 +281,10 @@
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
Modified: doctools/trunk/sphinx/roles.py
==============================================================================
--- doctools/trunk/sphinx/roles.py (original)
+++ doctools/trunk/sphinx/roles.py Mon Aug 6 12:49:52 2007
@@ -112,13 +112,13 @@
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))
@@ -149,7 +149,8 @@
'token' : xfileref_role,
'menuselection' : menusel_role,
- 'file' : file_role,
+ 'file' : emph_literal_role,
+ 'samp' : emph_literal_role,
}
for rolename, func in specific_docroles.iteritems():
More information about the Python-checkins
mailing list