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.
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

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

@ -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.

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 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.
::

8
Doc-3k/conf.py
View File

@ -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

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

@ -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.

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 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.
::

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 ','
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':

8
sphinx/environment.py
View File

@ -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

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}'))], []
_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():