Permalink
Browse files

Converted links to external topics so they use intersphinx extension …

…markup.

This allows to make these links more resilent to changes in the target URLs.
Thanks Jannis for the report and Aymeric Augustin for the patch.

Fixes #16586.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16720 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 9110257 commit 932b1b8d6dbd1a4d8e50aa0528c1489094f5704c @ramiro ramiro committed Sep 4, 2011
Showing with 284 additions and 378 deletions.
  1. +11 −1 docs/conf.py
  2. +5 −8 docs/faq/install.txt
  3. +4 −13 docs/glossary.txt
  4. +2 −4 docs/howto/custom-template-tags.txt
  5. +2 −4 docs/howto/deployment/modwsgi.txt
  6. +10 −14 docs/howto/outputting-csv.txt
  7. +7 −8 docs/howto/outputting-pdf.txt
  8. +8 −9 docs/internals/contributing/writing-code/branch-policy.txt
  9. +1 −1 docs/internals/contributing/writing-code/coding-style.txt
  10. +10 −12 docs/internals/contributing/writing-documentation.txt
  11. +2 −3 docs/intro/tutorial03.txt
  12. +5 −7 docs/misc/design-philosophies.txt
  13. +9 −11 docs/ref/class-based-views.txt
  14. +6 −6 docs/ref/contrib/csrf.txt
  15. +11 −7 docs/ref/contrib/gis/install.txt
  16. +6 −8 docs/ref/contrib/syndication.txt
  17. +1 −3 docs/ref/django-admin.txt
  18. +5 −9 docs/ref/exceptions.txt
  19. +4 −6 docs/ref/forms/fields.txt
  20. +15 −17 docs/ref/generic-views.txt
  21. +13 −20 docs/ref/models/fields.txt
  22. +1 −3 docs/ref/models/instances.txt
  23. +7 −11 docs/ref/models/querysets.txt
  24. +3 −6 docs/ref/request-response.txt
  25. +3 −5 docs/ref/settings.txt
  26. +4 −7 docs/ref/templates/builtins.txt
  27. +2 −4 docs/ref/unicode.txt
  28. +7 −12 docs/ref/utils.txt
  29. +2 −4 docs/releases/0.96.txt
  30. +2 −4 docs/releases/1.2.txt
  31. +2 −4 docs/releases/1.3-alpha-1.txt
  32. +2 −4 docs/releases/1.3.txt
  33. +1 −1 docs/releases/1.4.txt
  34. +1 −4 docs/topics/db/models.txt
  35. +9 −11 docs/topics/db/sql.txt
  36. +12 −16 docs/topics/email.txt
  37. +9 −11 docs/topics/http/file-uploads.txt
  38. +2 −4 docs/topics/http/sessions.txt
  39. +2 −2 docs/topics/http/shortcuts.txt
  40. +1 −1 docs/topics/http/views.txt
  41. +7 −9 docs/topics/install.txt
  42. +4 −6 docs/topics/logging.txt
  43. +64 −78 docs/topics/testing.txt
View
@@ -26,7 +26,7 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["djangodocs"]
+extensions = ["djangodocs", "sphinx.ext.intersphinx"]
# Add any paths that contain templates here, relative to this directory.
# templates_path = []
@@ -92,6 +92,16 @@
# Note: exclude_dirnames is new in Sphinx 0.5
exclude_dirnames = ['.svn']
+# Links to Python's docs should reference the most recent version of the 2.x
+# branch, which is located at this URL.
+intersphinx_mapping = {
+ 'python': ('http://docs.python.org/2.7', None),
+ 'sphinx': ('http://sphinx.pocoo.org/', None),
+}
+
+# Python's docs don't change every week.
+intersphinx_cache_limit = 90 # days
+
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
View
@@ -22,18 +22,17 @@ usage.
For a development environment -- if you just want to experiment with Django --
you don't need to have a separate Web server installed; Django comes with its
-own lightweight development server. For a production environment, Django
-follows the WSGI_ spec, which means it can run on a variety of server
-platforms. See :doc:`Deploying Django </howto/deployment/index>` for some
-popular alternatives. Also, the `server arrangements wiki page`_ contains
+own lightweight development server. For a production environment, Django follows
+the WSGI spec, :pep:`3333`, which means it can run on a variety of server
+platforms. See :doc:`Deploying Django </howto/deployment/index>` for some
+popular alternatives. Also, the `server arrangements wiki page`_ contains
details for several deployment strategies.
If you want to use Django with a database, which is probably the case, you'll
also need a database engine. PostgreSQL_ is recommended, because we're
PostgreSQL fans, and MySQL_, `SQLite 3`_, and Oracle_ are also supported.
.. _Python: http://www.python.org/
-.. _WSGI: http://www.python.org/dev/peps/pep-0333/
.. _server arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements
.. _PostgreSQL: http://www.postgresql.org/
.. _MySQL: http://www.mysql.com/
@@ -48,7 +47,7 @@ version of Python from 2.5 through 2.7, inclusive. However, newer versions of
Python are often faster, have more features, and are better supported. If you
use a newer version of Python you will also have access to some APIs that
aren't available under older versions of Python. For example, since Python 2.6,
-you can use the advanced string formatting described in `PEP 3101`_.
+you can use the advanced string formatting described in :pep:`3101`.
Third-party applications for use with Django are, of course, free to set their
own version requirements.
@@ -63,8 +62,6 @@ improvements and optimizations to the Python language since version 2.5, and
will help ease the process of dropping support for older Python versions on
the road to Python 3.
-.. _PEP 3101: http://www.python.org/dev/peps/pep-3101/
-
Can I use Django with Python 2.4?
---------------------------------
View
@@ -43,19 +43,10 @@ Glossary
property
Also known as "managed attributes", and a feature of Python since
- version 2.2. From `the property documentation`__:
-
- Properties are a neat way to implement attributes whose usage
- resembles attribute access, but whose implementation uses method
- calls. [...] You
- could only do this by overriding ``__getattr__`` and
- ``__setattr__``; but overriding ``__setattr__`` slows down all
- attribute assignments considerably, and overriding ``__getattr__``
- is always a bit tricky to get right. Properties let you do this
- painlessly, without having to override ``__getattr__`` or
- ``__setattr__``.
-
- __ http://www.python.org/download/releases/2.2/descrintro/#property
+ version 2.2. This is a neat way to implement attributes whose usage
+ resembles attribute access, but whose implementation uses method calls.
+
+ See :func:`property`.
queryset
An object representing some set of rows to be fetched from the database.
@@ -335,15 +335,13 @@ responsible for returning a ``Node`` instance based on the contents of the tag.
For example, let's write a template tag, ``{% current_time %}``, that displays
the current date/time, formatted according to a parameter given in the tag, in
-`strftime syntax`_. It's a good idea to decide the tag syntax before anything
-else. In our case, let's say the tag should be used like this:
+:func:`~time.strftime` syntax. It's a good idea to decide the tag syntax before
+anything else. In our case, let's say the tag should be used like this:
.. code-block:: html+django
<p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p>
-.. _`strftime syntax`: http://docs.python.org/library/time.html#time.strftime
-
The parser for this function should grab the parameter and create a ``Node``
object::
@@ -9,10 +9,8 @@ Django into production.
.. _mod_wsgi: http://code.google.com/p/modwsgi/
mod_wsgi is an Apache module which can be used to host any Python application
-which supports the `Python WSGI interface`_, including Django. Django will work
-with any version of Apache which supports mod_wsgi.
-
-.. _python wsgi interface: http://www.python.org/dev/peps/pep-0333/
+which supports the Python WSGI interface described in :pep:`3333`, including
+Django. Django will work with any version of Apache which supports mod_wsgi.
The `official mod_wsgi documentation`_ is fantastic; it's your source for all
the details about how to use mod_wsgi. You'll probably want to start with the
@@ -3,17 +3,15 @@ Outputting CSV with Django
==========================
This document explains how to output CSV (Comma Separated Values) dynamically
-using Django views. To do this, you can either use the `Python CSV library`_ or
-the Django template system.
-
-.. _Python CSV library: http://docs.python.org/library/csv.html
+using Django views. To do this, you can either use the Python CSV library or the
+Django template system.
Using the Python CSV library
============================
-Python comes with a CSV library, ``csv``. The key to using it with Django is
-that the ``csv`` module's CSV-creation capability acts on file-like objects, and
-Django's :class:`~django.http.HttpResponse` objects are file-like objects.
+Python comes with a CSV library, :mod:`csv`. The key to using it with Django is
+that the :mod:`csv` module's CSV-creation capability acts on file-like objects,
+and Django's :class:`~django.http.HttpResponse` objects are file-like objects.
Here's an example::
@@ -34,7 +32,7 @@ Here's an example::
The code and comments should be self-explanatory, but a few things deserve a
mention:
- * The response gets a special MIME type, ``text/csv``. This tells
+ * The response gets a special MIME type, :mimetype:`text/csv`. This tells
browsers that the document is a CSV file, rather than an HTML file. If
you leave this off, browsers will probably interpret the output as HTML,
which will result in ugly, scary gobbledygook in the browser window.
@@ -59,7 +57,7 @@ mention:
Handling Unicode
~~~~~~~~~~~~~~~~
-Python's ``csv`` module does not support Unicode input. Since Django uses
+Python's :mod:`csv` module does not support Unicode input. Since Django uses
Unicode internally this means strings read from sources such as
:class:`~django.http.HttpRequest` are potentially problematic. There are a few
options for handling this:
@@ -70,20 +68,18 @@ options for handling this:
section`_.
* Use the `python-unicodecsv module`_, which aims to be a drop-in
- replacement for ``csv`` that gracefully handles Unicode.
+ replacement for :mod:`csv` that gracefully handles Unicode.
-For more information, see the Python `CSV File Reading and Writing`_
-documentation.
+For more information, see the Python documentation of the :mod:`csv` module.
.. _`csv module's examples section`: http://docs.python.org/library/csv.html#examples
.. _`python-unicodecsv module`: https://github.com/jdunck/python-unicodecsv
-.. _`CSV File Reading and Writing`: http://docs.python.org/library/csv.html
Using the template system
=========================
Alternatively, you can use the :doc:`Django template system </topics/templates>`
-to generate CSV. This is lower-level than using the convenient Python ``csv``
+to generate CSV. This is lower-level than using the convenient Python :mod:`csv`
module, but the solution is presented here for completeness.
The idea here is to pass a list of items to your template, and have the
@@ -63,10 +63,11 @@ Here's a "Hello World" example::
The code and comments should be self-explanatory, but a few things deserve a
mention:
- * The response gets a special MIME type, ``application/pdf``. This tells
- browsers that the document is a PDF file, rather than an HTML file. If
- you leave this off, browsers will probably interpret the output as HTML,
- which would result in ugly, scary gobbledygook in the browser window.
+ * The response gets a special MIME type, :mimetype:`application/pdf`. This
+ tells browsers that the document is a PDF file, rather than an HTML file.
+ If you leave this off, browsers will probably interpret the output as
+ HTML, which would result in ugly, scary gobbledygook in the browser
+ window.
* The response gets an additional ``Content-Disposition`` header, which
contains the name of the PDF file. This filename is arbitrary: Call it
@@ -97,9 +98,9 @@ Complex PDFs
============
If you're creating a complex PDF document with ReportLab, consider using the
-cStringIO_ library as a temporary holding place for your PDF file. The cStringIO
+:mod:`cStringIO` library as a temporary holding place for your PDF file. This
library provides a file-like object interface that is particularly efficient.
-Here's the above "Hello World" example rewritten to use ``cStringIO``::
+Here's the above "Hello World" example rewritten to use :mod:`cStringIO`::
# Fall back to StringIO in environments where cStringIO is not available
try:
@@ -133,8 +134,6 @@ Here's the above "Hello World" example rewritten to use ``cStringIO``::
response.write(pdf)
return response
-.. _cStringIO: http://docs.python.org/library/stringio.html#module-cStringIO
-
Further resources
=================
@@ -146,14 +146,14 @@ Alternatively, you can use a symlink called ``django`` that points to the
location of the branch's ``django`` package. If you want to switch back, just
change the symlink to point to the old code.
-A third option is to use a `path file`_ (``<something>.pth``). First, make sure
-there are no files, directories or symlinks named ``django`` in your
-``site-packages`` directory. Then create a text file named ``django.pth`` and
-save it to your ``site-packages`` directory. That file should contain a path to
-your copy of Django on a single line and optional comments. Here is an example
-that points to multiple branches. Just uncomment the line for the branch you
-want to use ('Trunk' in this example) and make sure all other lines are
-commented::
+A third option is to use a path file (``<something>.pth``). This is a feature of
+the :mod:`site` module. First, make sure there are no files, directories or
+symlinks named ``django`` in your ``site-packages`` directory. Then create a
+text file named ``django.pth`` and save it to your ``site-packages`` directory.
+That file should contain a path to your copy of Django on a single line and
+optional comments. Here is an example that points to multiple branches. Just
+uncomment the line for the branch you want to use ('trunk' in this example) and
+make sure all other lines are commented::
# Trunk is a svn checkout of:
# http://code.djangoproject.com/svn/django/trunk/
@@ -168,5 +168,4 @@ commented::
# On windows a path may look like this:
# C:/path/to/<branch>
-.. _path file: http://docs.python.org/library/site.html
.. _django-developers: http://groups.google.com/group/django-developers
@@ -10,7 +10,7 @@ Python style
* Unless otherwise specified, follow :pep:`8`.
You could use a tool like `pep8`_ to check for some problems in this
- area, but remember that PEP 8 is only a guide, so respect the style of
+ area, but remember that :pep:`8` is only a guide, so respect the style of
the surrounding code as a primary goal.
* Use four spaces for indentation.
@@ -43,12 +43,10 @@ __ http://pygments.org
Then, building the HTML is easy; just ``make html`` (or ``make.bat html`` on
Windows) from the ``docs`` directory.
-To get started contributing, you'll want to read the `reStructuredText
-Primer`__. After that, you'll want to read about the `Sphinx-specific markup`__
-that's used to manage metadata, indexing, and cross-references.
-
-__ http://sphinx.pocoo.org/rest.html
-__ http://sphinx.pocoo.org/markup/
+To get started contributing, you'll want to read the :ref:`reStructuredText
+Primer <sphinx:rst-primer>`. After that, you'll want to read about the
+:ref:`Sphinx-specific markup <sphinx:sphinxmarkup>` that's used to manage
+metadata, indexing, and cross-references.
Commonly used terms
-------------------
@@ -113,6 +111,9 @@ documentation:
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.
+
Django-specific markup
----------------------
@@ -220,12 +221,9 @@ example:
You can find both in the :doc:`settings reference document
</ref/settings>`.
- We use the Sphinx doc_ cross reference element when we want to link to
- another document as a whole and the ref_ element when we want to link to
- an arbitrary location in a document.
-
-.. _doc: http://sphinx.pocoo.org/markup/inline.html#role-doc
-.. _ref: http://sphinx.pocoo.org/markup/inline.html#role-ref
+ 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:
@@ -122,14 +122,13 @@ the URLconf will look for ``myapp/``. In a request to
``http://www.example.com/myapp/?page=3``, the URLconf will look for ``myapp/``.
If you need help with regular expressions, see `Wikipedia's entry`_ and the
-`Python documentation`_. Also, the O'Reilly book "Mastering Regular Expressions"
-by Jeffrey Friedl is fantastic.
+documentation of the :mod:`re` module. Also, the O'Reilly book "Mastering
+Regular Expressions" by Jeffrey Friedl is fantastic.
Finally, a performance note: these regular expressions are compiled the first
time the URLconf module is loaded. They're super fast.
.. _Wikipedia's entry: http://en.wikipedia.org/wiki/Regular_expression
-.. _Python documentation: http://docs.python.org/library/re.html
Write your first view
=====================
@@ -73,13 +73,11 @@ as possible.
Explicit is better than implicit
--------------------------------
-This, a `core Python principle`_, means Django shouldn't do too much "magic."
-Magic shouldn't happen unless there's a really good reason for it. Magic is
-worth using only if it creates a huge convenience unattainable in other ways,
-and it isn't implemented in a way that confuses developers who are trying to
-learn how to use the feature.
-
-.. _`core Python principle`: http://www.python.org/dev/peps/pep-0020/
+This is a core Python principle listed in :pep:`20`, and it means Django
+shouldn't do too much "magic." Magic shouldn't happen unless there's a really
+good reason for it. Magic is worth using only if it creates a huge convenience
+unattainable in other ways, and it isn't implemented in a way that confuses
+developers who are trying to learn how to use the feature.
.. _consistency:
Oops, something went wrong. Retry.

0 comments on commit 932b1b8

Please sign in to comment.