diff --git a/Doc-26/conf.py b/Doc-26/conf.py index d24e769ad..944dd68d5 100644 --- a/Doc-26/conf.py +++ b/Doc-26/conf.py @@ -23,6 +23,9 @@ today = '' # 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 @@ use_smartypants = True # 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 diff --git a/Doc-26/documenting/markup.rst b/Doc-26/documenting/markup.rst index 4f63ac5fd..831fad977 100644 --- a/Doc-26/documenting/markup.rst +++ b/Doc-26/documenting/markup.rst @@ -474,6 +474,14 @@ in a different style: 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. diff --git a/Doc-26/library/time.rst b/Doc-26/library/time.rst index 8bcc6dda7..48022729c 100644 --- a/Doc-26/library/time.rst +++ b/Doc-26/library/time.rst @@ -445,44 +445,44 @@ The module defines the following functions and data items: 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. :: diff --git a/Doc-3k/conf.py b/Doc-3k/conf.py index 160114f46..6736f533b 100644 --- a/Doc-3k/conf.py +++ b/Doc-3k/conf.py @@ -23,6 +23,9 @@ today = '' # 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 @@ use_smartypants = True # 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 diff --git a/Doc-3k/documenting/markup.rst b/Doc-3k/documenting/markup.rst index 4f63ac5fd..831fad977 100644 --- a/Doc-3k/documenting/markup.rst +++ b/Doc-3k/documenting/markup.rst @@ -474,6 +474,14 @@ in a different style: 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. diff --git a/Doc-3k/library/time.rst b/Doc-3k/library/time.rst index 24a93e1da..0357d9931 100644 --- a/Doc-3k/library/time.rst +++ b/Doc-3k/library/time.rst @@ -445,44 +445,44 @@ The module defines the following functions and data items: 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. :: diff --git a/sphinx/directives.py b/sphinx/directives.py index 3c5f15329..0fc04a879 100644 --- a/sphinx/directives.py +++ b/sphinx/directives.py @@ -113,7 +113,7 @@ py_sig_re = re.compile(r'''^([\w.]*\.)? # class names 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 @@ def parse_py_signature(signode, sig, desctype, currmodule, currclass): 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 @@ def desc_directive(desctype, arguments, options, content, lineno, 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': diff --git a/sphinx/environment.py b/sphinx/environment.py index 4b6bdfe49..d7dcdc1cf 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -281,10 +281,10 @@ class BuildEnvironment: 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 diff --git a/sphinx/roles.py b/sphinx/roles.py index b43ece085..622764311 100644 --- a/sphinx/roles.py +++ b/sphinx/roles.py @@ -112,13 +112,13 @@ def menusel_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): 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 @@ specific_docroles = { 'token' : xfileref_role, 'menuselection' : menusel_role, - 'file' : file_role, + 'file' : emph_literal_role, + 'samp' : emph_literal_role, } for rolename, func in specific_docroles.iteritems():