IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Add module names even to names in classes. Add a config option for that.

Browse Source 
Add a :samp: role for highlighting text inside literal code.
Fix the time module docs.
This commit is contained in:
Georg Brandl 2007-08-06 10:49:52 +00:00
parent cc5aedc6ce
commit 79f1a1eecb
9 changed files with 104 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
Doc-26/conf.py
View File

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

8
Doc-26/documenting/markup.rst
View File

@ -474,6 +474,14 @@ in a different style:
A regular expression. Quotes should not be included. 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 .. describe:: var
A Python or C variable or parameter name. A Python or C variable or parameter name.

52
Doc-26/library/time.rst
View File

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

8
Doc-3k/conf.py
View File

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

8
Doc-3k/documenting/markup.rst
View File

@ -474,6 +474,14 @@ in a different style:
A regular expression. Quotes should not be included. 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 .. describe:: var
A Python or C variable or parameter name. A Python or C variable or parameter name.

52
Doc-3k/library/time.rst
View File

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

28
sphinx/directives.py
View File

@ -113,7 +113,7 @@ py_sig_re = re.compile(r'''^([\w.]*\.)? # class names
py_paramlist_re = re.compile(r'([\[\],])') # split at '[', ']' and ',' 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. Transform a python signature into RST nodes.
Return the fully qualified name of the thing. 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 if m is None: raise ValueError
classname, name, arglist = m.groups() classname, name, arglist = m.groups()
if currclass: if env.currclass:
if classname and classname.startswith(currclass): if classname and classname.startswith(env.currclass):
fullname = classname + name fullname = classname + name
classname = classname[len(currclass):].lstrip('.') classname = classname[len(env.currclass):].lstrip('.')
elif classname: elif classname:
fullname = currclass + '.' + classname + name fullname = env.currclass + '.' + classname + name
else: else:
fullname = currclass + '.' + name fullname = env.currclass + '.' + name
else: else:
fullname = classname + name if classname else name 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 are a special case, since they are documented in the
# 'exceptions' module. # 'exceptions' module.
elif currmodule and currmodule != 'exceptions': if env.config.get('add_module_names', True) and \
signode += addnodes.desc_classname(currmodule+'.', currmodule+'.') 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) signode += addnodes.desc_name(name, name)
if not arglist: if not arglist:
@ -287,8 +290,7 @@ def desc_directive(desctype, arguments, options, content, lineno,
try: try:
if desctype in ('function', 'data', 'class', 'exception', if desctype in ('function', 'data', 'class', 'exception',
'method', 'attribute'): 'method', 'attribute'):
name = parse_py_signature(signode, sig, desctype, name = parse_py_signature(signode, sig, desctype, env)
env.currmodule, env.currclass)
elif desctype in ('cfunction', 'cmember', 'cmacro', 'ctype', 'cvar'): elif desctype in ('cfunction', 'cmember', 'cmacro', 'ctype', 'cvar'):
name = parse_c_signature(signode, sig, desctype) name = parse_c_signature(signode, sig, desctype)
elif desctype == 'opcode': elif desctype == 'opcode':

8
sphinx/environment.py
View File

@ -281,10 +281,10 @@ class BuildEnvironment:
if newmtime == mtime: if newmtime == mtime:
continue continue
# check the MD5 # check the MD5
with file(path.join(self.srcdir, filename), 'rb') as f: #with file(path.join(self.srcdir, filename), 'rb') as f:
newmd5 = hashlib.md5(f.read()).digest() # newmd5 = hashlib.md5(f.read()).digest()
if newmd5 != md5: #if newmd5 != md5:
changed.append(filename) changed.append(filename)
return removed, changed return removed, changed

9
sphinx/roles.py
View File

@ -112,13 +112,13 @@ def menusel_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
rawtext, utils.unescape(text).replace('-->', u'\N{TRIANGULAR BULLET}'))], [] 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) text = utils.unescape(text)
retnodes = [] retnodes = []
pos = 0 pos = 0
for m in _filevar_re.finditer(text): for m in _litvar_re.finditer(text):
if m.start() > pos: if m.start() > pos:
txt = text[pos:m.start()] txt = text[pos:m.start()]
retnodes.append(nodes.literal(txt, txt)) retnodes.append(nodes.literal(txt, txt))
@ -149,7 +149,8 @@ specific_docroles = {
'token' : xfileref_role, 'token' : xfileref_role,
'menuselection' : menusel_role, 'menuselection' : menusel_role,
'file' : file_role, 'file' : emph_literal_role,
'samp' : emph_literal_role,
} }
for rolename, func in specific_docroles.iteritems(): for rolename, func in specific_docroles.iteritems():