← Back to branch summary

~ubuntu-branches/ubuntu/quantal/python-django/quantal

« back to all changes in this revision

Viewing changes to docs/internals/documentation.txt

  • Committer: Bazaar Package Importer
  • Author(s): Scott James Remnant
  • Date: 2008-11-15 19:15:33 UTC
  • mfrom: (1.1.6 upstream)
  • Revision ID: james.westby@ubuntu.com-20081115191533-xbt1ut2xf4fvwtvc
Tags: 1.0.1-0ubuntu1
* New upstream release:
  - Bug fixes.

* The tests/ sub-directory appaers to have been dropped upstream, so pull
  our patch to workaround the tests and modify the rules.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/internals/documentation.txt
28
28
semantic markup you can add the better. So::
29
29
 
30
30
    Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
31
 
    
 
31
 
32
32
Isn't nearly as helpful as::
33
33
 
34
34
    Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
35
 
    
36
 
This is because Sphinx will generate proper links for the later, which greatly
 
35
 
 
36
This is because Sphinx will generate proper links for the latter, which greatly
37
37
helps readers. There's basically no limit to the amount of useful markup you can
38
38
add.
39
39
 
45
45
__ http://sphinx.pocoo.org/markup/desc.html
46
46
 
47
47
    * Settings::
48
 
    
 
48
 
49
49
            .. setting:: INSTALLED_APPS
50
 
                
 
50
 
51
51
      To link to a setting, use ``:setting:`INSTALLED_APPS```.
52
 
      
 
52
 
53
53
    * Template tags::
54
 
   
 
54
 
55
55
            .. templatetag:: regroup
56
 
    
 
56
 
57
57
      To link, use ``:ttag:`regroup```.
58
 
     
 
58
 
59
59
    * Template filters::
60
 
   
 
60
 
61
61
            .. templatefilter:: linebreaksbr
62
 
       
 
62
 
63
63
      To link, use ``:tfilter:`linebreaksbr```.
64
 
      
 
64
 
65
65
    * Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``)::
66
 
    
 
66
 
67
67
            .. fieldlookup:: exact
68
 
            
 
68
 
69
69
      To link, use ``:lookup:`exact```.
70
 
      
 
70
 
71
71
    * ``django-admin`` commands::
72
 
    
 
72
 
73
73
            .. django-admin:: syncdb
74
 
            
 
74
 
75
75
      To link, use ``:djadmin:`syncdb```.
76
 
      
 
76
 
77
77
    * ``django-admin`` command-line options::
78
 
    
 
78
 
79
79
            .. django-admin-option:: --traceback
80
 
            
 
80
 
81
81
      To link, use ``:djadminopt:`--traceback```.
82
82
 
83
83
An example
86
86
For a quick example of how it all fits together, check this out:
87
87
 
88
88
    * First, the ``ref/settings.txt`` document starts out like this::
89
 
    
 
89
 
90
90
        .. _ref-settings:
91
91
 
92
92
        Available settings
93
93
        ==================
94
 
        
 
94
 
95
95
        ...
96
 
        
 
96
 
97
97
    * Next, if you look at the ``topics/settings.txt`` document, you can see how
98
98
      a link to ``ref/settings`` works::
99
 
     
 
99
 
100
100
        Available settings
101
101
        ==================
102
102
 
103
103
        For a full list of available settings, see the :ref:`settings reference
104
104
        <ref-settings>`.
105
 
        
 
105
 
106
106
    * Next, notice how the settings (right now just the top few) are annotated::
107
 
   
 
107
 
108
108
        .. setting:: ADMIN_FOR
109
109
 
110
110
        ADMIN_FOR
115
115
        Used for admin-site settings modules, this should be a tuple of settings
116
116
        modules (in the format ``'foo.bar.baz'``) for which this site is an
117
117
        admin.
118
 
        
 
118
 
119
119
        The admin site uses this in its automatically-introspected
120
120
        documentation of models, views and template tags.
121
 
        
 
121
 
122
122
      This marks up the following header as the "canonical" target for the
123
123
      setting ``ADMIN_FOR`` This means any time I talk about ``ADMIN_FOR``, I
124
124
      can reference it using ``:setting:`ADMIN_FOR```.
125
 
     
 
125
 
126
126
That's basically how everything fits together.
127
127
 
128
128
TODO
134
134
      this TODO item my permission and license) into
135
135
      ``topics/generic-views.txt``; remove the intro material from
136
136
      ``ref/generic-views.txt`` and just leave the function reference.
137
 
    
 
137
 
138
138
    * Change the "Added/changed in development version" callouts to proper
139
139
      Sphinx ``.. versionadded::`` or ``.. versionchanged::`` directives.
140
 
    
 
140
 
141
141
    * Check for and fix malformed links. Do this by running ``make linkcheck``
142
142
      and fix all of the 300+ errors/warnings.
143
 
      
144
 
      In particular, look at all the relative links; these need to be 
 
143
 
 
144
      In particular, look at all the relative links; these need to be
145
145
      changed to proper references.
146
 
      
 
146
 
147
147
    * Most of the various ``index.txt`` documents have *very* short or even
148
148
      non-existent intro text. Each of those documents needs a good short intro
149
149
      the content below that point.
150
150
 
151
151
    * The glossary is very perfunctory. It needs to be filled out.
152
 
    
 
152
 
153
153
    * Add more metadata targets: there's lots of places that look like::
154
 
    
 
154
 
155
155
            ``File.close()``
156
156
            ~~~~~~~~~~~~~~~~
157
 
        
 
157
 
158
158
      \... these should be::
159
 
      
 
159
 
160
160
            .. method:: File.close()
161
 
            
 
161
 
162
162
      That is, use metadata instead of titles.
163
 
      
 
163
 
164
164
    * Add more links -- nearly everything that's an inline code literal
165
 
      right now can probably be turned into a xref. 
166
 
      
 
165
      right now can probably be turned into a xref.
 
166
 
167
167
      See the ``literals_to_xrefs.py`` file in ``_ext`` -- it's a shell script
168
168
      to help do this work.
169
169
 
170
170
      This will probably be a continuing, never-ending project.
171
171
 
172
172
    * Add `info field lists`__ where appropriate.
173
 
    
 
173
 
174
174
      __ http://sphinx.pocoo.org/markup/desc.html#info-field-lists
175
 
      
 
175
 
176
176
    * Add ``.. code-block:: <lang>`` to literal blocks so that they get
177
177
      highlighted.
178
178
 
189
189
      "crossref" directives. Others (``.. class::``, e.g.) generate their own
190
190
      markup; these should go inside the section they're describing. These are
191
191
      called "description units".
192
 
      
 
192
 
193
193
      You can tell which are which by looking at in :file:`_ext/djangodocs.py`;
194
194
      it registers roles as one of the other.
195
 
      
 
195
 
196
196
    * When referring to classes/functions/modules, etc., you'll want to use the
197
197
      fully-qualified name of the target
198
 
      (``:class:`django.contrib.contenttypes.models.ContentType```). 
199
 
      
 
198
      (``:class:`django.contrib.contenttypes.models.ContentType```).
 
199
 
200
200
      Since this doesn't look all that awesome in the output -- it shows the
201
201
      entire path to the object -- you can prefix the target with a ``~``
202
202
      (that's a tilde) to get just the "last bit" of that path. So