diff options
Diffstat (limited to 'docs/internals/contributing/writing-documentation.txt')
| -rw-r--r-- | docs/internals/contributing/writing-documentation.txt | 260 |
1 files changed, 130 insertions, 130 deletions
diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 2d08dba389..d61650a72e 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -9,11 +9,11 @@ possible. Documentation changes generally come in two forms: - * General improvements: typo corrections, error fixes and better - explanations through clearer writing and more examples. +* General improvements: typo corrections, error fixes and better + explanations through clearer writing and more examples. - * New features: documentation of features that have been added to the - framework since the last release. +* New features: documentation of features that have been added to the + framework since the last release. This section explains how writers can craft their documentation changes in the most useful and least error-prone ways. @@ -54,37 +54,37 @@ Commonly used terms Here are some style guidelines on commonly used terms throughout the documentation: - * **Django** -- when referring to the framework, capitalize Django. It is - lowercase only in Python code and in the djangoproject.com logo. +* **Django** -- when referring to the framework, capitalize Django. It is + lowercase only in Python code and in the djangoproject.com logo. - * **email** -- no hyphen. +* **email** -- no hyphen. - * **MySQL**, **PostgreSQL**, **SQLite** +* **MySQL**, **PostgreSQL**, **SQLite** - * **Python** -- when referring to the language, capitalize Python. +* **Python** -- when referring to the language, capitalize Python. - * **realize**, **customize**, **initialize**, etc. -- use the American - "ize" suffix, not "ise." +* **realize**, **customize**, **initialize**, etc. -- use the American + "ize" suffix, not "ise." - * **subclass** -- it's a single word without a hyphen, both as a verb - ("subclass that model") and as a noun ("create a subclass"). +* **subclass** -- it's a single word without a hyphen, both as a verb + ("subclass that model") and as a noun ("create a subclass"). - * **Web**, **World Wide Web**, **the Web** -- note Web is always - capitalized when referring to the World Wide Web. +* **Web**, **World Wide Web**, **the Web** -- note Web is always + capitalized when referring to the World Wide Web. - * **Web site** -- use two words, with Web capitalized. +* **Web site** -- use two words, with Web capitalized. Django-specific terminology --------------------------- - * **model** -- it's not capitalized. +* **model** -- it's not capitalized. - * **template** -- it's not capitalized. +* **template** -- it's not capitalized. - * **URLconf** -- use three capitalized letters, with no space before - "conf." +* **URLconf** -- use three capitalized letters, with no space before + "conf." - * **view** -- it's not capitalized. +* **view** -- it's not capitalized. Guidelines for reStructuredText files ------------------------------------- @@ -92,27 +92,27 @@ Guidelines for reStructuredText files These guidelines regulate the format of our reST (reStructuredText) documentation: - * In section titles, capitalize only initial words and proper nouns. +* In section titles, capitalize only initial words and proper nouns. - * Wrap the documentation at 80 characters wide, unless a code example - is significantly less readable when split over two lines, or for another - good reason. +* Wrap the documentation at 80 characters wide, unless a code example + is significantly less readable when split over two lines, or for another + good reason. - * The main thing to keep in mind as you write and edit docs is that the - more semantic markup you can add the better. So:: +* The main thing to keep in mind as you write and edit docs is that the + more semantic markup you can add the better. So:: - Add ``django.contrib.auth`` to your ``INSTALLED_APPS``... + Add ``django.contrib.auth`` to your ``INSTALLED_APPS``... - Isn't nearly as helpful as:: + Isn't nearly as helpful as:: - Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`... + Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`... - This is because Sphinx will generate proper links for the latter, which - greatly helps readers. There's basically no limit to the amount of - useful markup you can add. + This is because Sphinx will generate proper links for the latter, which + greatly helps readers. There's basically no limit to the amount of + useful markup you can add. - * Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx' - documentation. +* Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx' + documentation. Django-specific markup ---------------------- @@ -122,41 +122,41 @@ description units: __ http://sphinx.pocoo.org/markup/desc.html - * Settings:: +* Settings:: - .. setting:: INSTALLED_APPS + .. setting:: INSTALLED_APPS - To link to a setting, use ``:setting:`INSTALLED_APPS```. + To link to a setting, use ``:setting:`INSTALLED_APPS```. - * Template tags:: +* Template tags:: - .. templatetag:: regroup + .. templatetag:: regroup - To link, use ``:ttag:`regroup```. + To link, use ``:ttag:`regroup```. - * Template filters:: +* Template filters:: - .. templatefilter:: linebreaksbr + .. templatefilter:: linebreaksbr - To link, use ``:tfilter:`linebreaksbr```. + To link, use ``:tfilter:`linebreaksbr```. - * Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``):: +* Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``):: - .. fieldlookup:: exact + .. fieldlookup:: exact - To link, use ``:lookup:`exact```. + To link, use ``:lookup:`exact```. - * ``django-admin`` commands:: +* ``django-admin`` commands:: - .. django-admin:: syncdb + .. django-admin:: syncdb - To link, use ``:djadmin:`syncdb```. + To link, use ``:djadmin:`syncdb```. - * ``django-admin`` command-line options:: +* ``django-admin`` command-line options:: - .. django-admin-option:: --traceback + .. django-admin-option:: --traceback - To link, use ``:djadminopt:`--traceback```. + To link, use ``:djadminopt:`--traceback```. .. _documenting-new-features: @@ -184,68 +184,68 @@ An example For a quick example of how it all fits together, consider this hypothetical example: - * First, the ``ref/settings.txt`` document could have an overall layout - like this: +* First, the ``ref/settings.txt`` document could have an overall layout + like this: - .. code-block:: rst + .. code-block:: rst - ======== - Settings - ======== + ======== + Settings + ======== - ... + ... - .. _available-settings: + .. _available-settings: - Available settings - ================== + Available settings + ================== - ... + ... - .. _deprecated-settings: + .. _deprecated-settings: - Deprecated settings - =================== + Deprecated settings + =================== - ... + ... - * Next, the ``topics/settings.txt`` document could contain something like - this: +* Next, the ``topics/settings.txt`` document could contain something like + this: - .. code-block:: rst + .. code-block:: rst - You can access a :ref:`listing of all available settings - <available-settings>`. For a list of deprecated settings see - :ref:`deprecated-settings`. + You can access a :ref:`listing of all available settings + <available-settings>`. For a list of deprecated settings see + :ref:`deprecated-settings`. - You can find both in the :doc:`settings reference document - </ref/settings>`. + You can find both in the :doc:`settings reference document + </ref/settings>`. - We use the Sphinx :rst:role:`doc` cross reference element when we want to - link to another document as a whole and the :rst:role:`ref` element when - we want to link to an arbitrary location in a document. + We use the Sphinx :rst:role:`doc` cross reference element when we want to + link to another document as a whole and the :rst:role:`ref` element when + we want to link to an arbitrary location in a document. - * Next, notice how the settings are annotated: +* Next, notice how the settings are annotated: - .. code-block:: rst + .. code-block:: rst - .. setting:: ADMIN_FOR + .. setting:: ADMIN_FOR - ADMIN_FOR - --------- + ADMIN_FOR + --------- - Default: ``()`` (Empty tuple) + Default: ``()`` (Empty tuple) - Used for admin-site settings modules, this should be a tuple of - settings modules (in the format ``'foo.bar.baz'``) for which this site - is an admin. + Used for admin-site settings modules, this should be a tuple of + settings modules (in the format ``'foo.bar.baz'``) for which this site + is an admin. - The admin site uses this in its automatically-introspected - documentation of models, views and template tags. + The admin site uses this in its automatically-introspected + documentation of models, views and template tags. - This marks up the following header as the "canonical" target for the - setting ``ADMIN_FOR`` This means any time I talk about ``ADMIN_FOR``, - I can reference it using ``:setting:`ADMIN_FOR```. + This marks up the following header as the "canonical" target for the + setting ``ADMIN_FOR`` This means any time I talk about ``ADMIN_FOR``, + I can reference it using ``:setting:`ADMIN_FOR```. That's basically how everything fits together. @@ -257,57 +257,57 @@ Improving the documentation A few small improvements can be made to make the documentation read and look better: - * Most of the various ``index.txt`` documents have *very* short or even - non-existent intro text. Each of those documents needs a good short - intro the content below that point. +* Most of the various ``index.txt`` documents have *very* short or even + non-existent intro text. Each of those documents needs a good short + intro the content below that point. - * The glossary is very perfunctory. It needs to be filled out. +* The glossary is very perfunctory. It needs to be filled out. - * Add more metadata targets. Lots of places look like:: +* Add more metadata targets. Lots of places look like:: - ``File.close()`` - ~~~~~~~~~~~~~~~~ + ``File.close()`` + ~~~~~~~~~~~~~~~~ - \... these should be:: + \... these should be:: - .. method:: File.close() + .. method:: File.close() - That is, use metadata instead of titles. + That is, use metadata instead of titles. - * Add more links -- nearly everything that's an inline code literal - right now can probably be turned into a xref. +* Add more links -- nearly everything that's an inline code literal + right now can probably be turned into a xref. - See the ``literals_to_xrefs.py`` file in ``_ext`` -- it's a shell script - to help do this work. + See the ``literals_to_xrefs.py`` file in ``_ext`` -- it's a shell script + to help do this work. - This will probably be a continuing, never-ending project. + This will probably be a continuing, never-ending project. - * Add `info field lists`__ where appropriate. +* Add `info field lists`__ where appropriate. - __ http://sphinx.pocoo.org/markup/desc.html#info-field-lists + __ http://sphinx.pocoo.org/markup/desc.html#info-field-lists - * Whenever possible, use links. So, use ``:setting:`ADMIN_FOR``` instead - of ````ADMIN_FOR````. +* Whenever possible, use links. So, use ``:setting:`ADMIN_FOR``` instead + of ````ADMIN_FOR````. - * Use directives where appropriate. Some directives - (e.g. ``.. setting::``) are prefix-style directives; they go *before* - the unit they're describing. These are known as "crossref" directives. - Others (e.g. ``.. class::``) generate their own markup; these should go - inside the section they're describing. These are called - "description units". +* Use directives where appropriate. Some directives + (e.g. ``.. setting::``) are prefix-style directives; they go *before* + the unit they're describing. These are known as "crossref" directives. + Others (e.g. ``.. class::``) generate their own markup; these should go + inside the section they're describing. These are called + "description units". - You can tell which are which by looking at in - :file:`_ext/djangodocs.py`; it registers roles as one of the other. + You can tell which are which by looking at in + :file:`_ext/djangodocs.py`; it registers roles as one of the other. - * Add ``.. code-block:: <lang>`` to literal blocks so that they get - highlighted. +* Add ``.. code-block:: <lang>`` to literal blocks so that they get + highlighted. - * When referring to classes/functions/modules, etc., you'll want to use - the fully-qualified name of the target - (``:class:`django.contrib.contenttypes.models.ContentType```). +* When referring to classes/functions/modules, etc., you'll want to use + the fully-qualified name of the target + (``:class:`django.contrib.contenttypes.models.ContentType```). - Since this doesn't look all that awesome in the output -- it shows the - entire path to the object -- you can prefix the target with a ``~`` - (that's a tilde) to get just the "last bit" of that path. So - ``:class:`~django.contrib.contenttypes.models.ContentType``` will just - display a link with the title "ContentType". + Since this doesn't look all that awesome in the output -- it shows the + entire path to the object -- you can prefix the target with a ``~`` + (that's a tilde) to get just the "last bit" of that path. So + ``:class:`~django.contrib.contenttypes.models.ContentType``` will just + display a link with the title "ContentType". |