Changeset 2143 in main for trunk/docs


Ignore:
Timestamp:
03/11/13 14:33:29 (6 years ago)
Author:
pcosquer
Message:

docs: add a stub page on richtext stuff

Location:
trunk/docs/en
Files:
1 added
3 edited

Legend:

Unmodified
Added
Removed
  • trunk/docs/en/_ext/djangodocs.py

    r2106 r2143  
    22Sphinx plugins for Django documentation. 
    33""" 
    4 import json 
    5 import os 
    64import re 
     5# RE for option descriptions without a '--' prefix 
    76 
    8 from docutils import nodes, transforms 
    9  
    10 from sphinx import addnodes, roles, __version__ as sphinx_ver 
    11 from sphinx.builders.html import StandaloneHTMLBuilder 
    12 from sphinx.writers.html import SmartyPantsHTMLTranslator 
    13 from sphinx.util.console import bold 
    14 from sphinx.util.compat import Directive 
    15  
    16 # RE for option descriptions without a '--' prefix 
    177simple_option_desc_re = re.compile( 
    188    r'([-_a-zA-Z0-9]+)(\s*.*?)(?=,\s+(?:/|-|--)|$)') 
     
    3929        indextemplate = "pair: %s; field lookup type", 
    4030    ) 
    41     app.add_description_unit( 
    42         directivename = "django-admin", 
    43         rolename = "djadmin", 
    44         indextemplate = "pair: %s; django-admin command", 
    45         parse_node = parse_django_admin_node, 
    46     ) 
    47     app.add_description_unit( 
    48         directivename = "django-admin-option", 
    49         rolename = "djadminopt", 
    50         indextemplate = "pair: %s; django-admin command-line option", 
    51         parse_node = parse_django_adminopt_node, 
    52     ) 
    53     app.add_config_value('django_next_version', '0.0', True) 
    54     app.add_directive('versionadded', VersionDirective) 
    55     app.add_directive('versionchanged', VersionDirective) 
    56     app.add_builder(DjangoStandaloneHTMLBuilder) 
    5731 
    58  
    59 class VersionDirective(Directive): 
    60     has_content = True 
    61     required_arguments = 1 
    62     optional_arguments = 1 
    63     final_argument_whitespace = True 
    64     option_spec = {} 
    65  
    66     def run(self): 
    67         env = self.state.document.settings.env 
    68         ret = [] 
    69         node = addnodes.versionmodified() 
    70         ret.append(node) 
    71         if self.arguments[0] == env.config.django_next_version: 
    72             node['version'] = "Development version" 
    73         else: 
    74             node['version'] = self.arguments[0] 
    75         node['type'] = self.name 
    76         if len(self.arguments) == 2: 
    77             inodes, messages = self.state.inline_text(self.arguments[1], self.lineno+1) 
    78             node.extend(inodes) 
    79             if self.content: 
    80                 self.state.nested_parse(self.content, self.content_offset, node) 
    81             ret = ret + messages 
    82         env.note_versionchange(node['type'], node['version'], node, self.lineno) 
    83         return ret 
    84  
    85  
    86 class DjangoHTMLTranslator(SmartyPantsHTMLTranslator): 
    87     """ 
    88 Django-specific reST to HTML tweaks. 
    89 """ 
    90  
    91     # Don't use border=1, which docutils does by default. 
    92     def visit_table(self, node): 
    93         self._table_row_index = 0 # Needed by Sphinx 
    94         self.body.append(self.starttag(node, 'table', CLASS='docutils')) 
    95  
    96     # <big>? Really? 
    97     def visit_desc_parameterlist(self, node): 
    98         self.body.append('(') 
    99         self.first_param = 1 
    100         self.param_separator = node.child_text_separator 
    101  
    102     def depart_desc_parameterlist(self, node): 
    103         self.body.append(')') 
    104  
    105     if sphinx_ver < '1.0.8': 
    106         # 
    107         # Don't apply smartypants to literal blocks 
    108         # 
    109         def visit_literal_block(self, node): 
    110             self.no_smarty += 1 
    111             SmartyPantsHTMLTranslator.visit_literal_block(self, node) 
    112  
    113         def depart_literal_block(self, node): 
    114             SmartyPantsHTMLTranslator.depart_literal_block(self, node) 
    115             self.no_smarty -= 1 
    116  
    117     # 
    118     # Turn the "new in version" stuff (versionadded/versionchanged) into a 
    119     # better callout -- the Sphinx default is just a little span, 
    120     # which is a bit less obvious that I'd like. 
    121     # 
    122     # FIXME: these messages are all hardcoded in English. We need to change 
    123     # that to accomodate other language docs, but I can't work out how to make 
    124     # that work. 
    125     # 
    126     version_text = { 
    127         'deprecated': 'Deprecated in Django %s', 
    128         'versionchanged': 'Changed in Django %s', 
    129         'versionadded': 'New in Django %s', 
    130     } 
    131  
    132     def visit_versionmodified(self, node): 
    133         self.body.append( 
    134             self.starttag(node, 'div', CLASS=node['type']) 
    135         ) 
    136         title = "%s%s" % ( 
    137             self.version_text[node['type']] % node['version'], 
    138             len(node) and ":" or "." 
    139         ) 
    140         self.body.append('<span class="title">%s</span> ' % title) 
    141  
    142     def depart_versionmodified(self, node): 
    143         self.body.append("</div>\n") 
    144  
    145     # Give each section a unique ID -- nice for custom CSS hooks 
    146     def visit_section(self, node): 
    147         old_ids = node.get('ids', []) 
    148         node['ids'] = ['s-' + i for i in old_ids] 
    149         node['ids'].extend(old_ids) 
    150         SmartyPantsHTMLTranslator.visit_section(self, node) 
    151         node['ids'] = old_ids 
    152  
    153 def parse_django_admin_node(env, sig, signode): 
    154     command = sig.split(' ')[0] 
    155     env._django_curr_admin_command = command 
    156     title = "django-admin.py %s" % sig 
    157     signode += addnodes.desc_name(title, title) 
    158     return sig 
    159  
    160 def parse_django_adminopt_node(env, sig, signode): 
    161     """A copy of sphinx.directives.CmdoptionDesc.parse_signature()""" 
    162     from sphinx.domains.std import option_desc_re 
    163     count = 0 
    164     firstname = '' 
    165     for m in option_desc_re.finditer(sig): 
    166         optname, args = m.groups() 
    167         if count: 
    168             signode += addnodes.desc_addname(', ', ', ') 
    169         signode += addnodes.desc_name(optname, optname) 
    170         signode += addnodes.desc_addname(args, args) 
    171         if not count: 
    172             firstname = optname 
    173         count += 1 
    174     if not count: 
    175         for m in simple_option_desc_re.finditer(sig): 
    176             optname, args = m.groups() 
    177             if count: 
    178                 signode += addnodes.desc_addname(', ', ', ') 
    179             signode += addnodes.desc_name(optname, optname) 
    180             signode += addnodes.desc_addname(args, args) 
    181             if not count: 
    182                 firstname = optname 
    183             count += 1 
    184     if not firstname: 
    185         raise ValueError 
    186     return firstname 
    187  
    188  
    189 class DjangoStandaloneHTMLBuilder(StandaloneHTMLBuilder): 
    190     """ 
    191 Subclass to add some extra things we need. 
    192 """ 
    193  
    194     name = 'djangohtml' 
    195  
    196     def finish(self): 
    197         super(DjangoStandaloneHTMLBuilder, self).finish() 
    198         self.info(bold("writing templatebuiltins.js...")) 
    199         xrefs = self.env.domaindata["std"]["objects"] 
    200         templatebuiltins = { 
    201             "ttags": [n for ((t, n), (l, a)) in xrefs.items() 
    202                         if t == "templatetag" and l == "ref/templates/builtins"], 
    203             "tfilters": [n for ((t, n), (l, a)) in xrefs.items() 
    204                         if t == "templatefilter" and l == "ref/templates/builtins"], 
    205         } 
    206         outfilename = os.path.join(self.outdir, "templatebuiltins.js") 
    207         with open(outfilename, 'w') as fp: 
    208             fp.write('var django_template_builtins = ') 
    209             json.dump(templatebuiltins, fp) 
    210             fp.write(';\n') 
  • trunk/docs/en/devel/index.rst

    r1485 r2143  
    2828    bom 
    2929    publication 
     30    richtext 
    3031    testing 
  • trunk/docs/en/devel/modules/views/ajax.rst

    r547 r2143  
    55.. automodule:: plmapp.views.ajax 
    66    :members: 
     7    :show-inheritance: 
    78    :undoc-members: 
    8     :show-inheritance: 
    99   
Note: See TracChangeset for help on using the changeset viewer.