diff options
Diffstat (limited to 'docs/intro')
| -rw-r--r-- | docs/intro/index.txt | 2 | ||||
| -rw-r--r-- | docs/intro/install.txt | 24 | ||||
| -rw-r--r-- | docs/intro/overview.txt | 26 | ||||
| -rw-r--r-- | docs/intro/tutorial01.txt | 42 | ||||
| -rw-r--r-- | docs/intro/tutorial02.txt | 10 | ||||
| -rw-r--r-- | docs/intro/tutorial03.txt | 16 | ||||
| -rw-r--r-- | docs/intro/tutorial04.txt | 22 | ||||
| -rw-r--r-- | docs/intro/whatsnext.txt | 41 |
8 files changed, 83 insertions, 100 deletions
diff --git a/docs/intro/index.txt b/docs/intro/index.txt index 2135bc7fe9..90ee627ba6 100644 --- a/docs/intro/index.txt +++ b/docs/intro/index.txt @@ -1,5 +1,3 @@ -.. _intro-index: - Getting started =============== diff --git a/docs/intro/install.txt b/docs/intro/install.txt index 901bde01c2..95728c75fc 100644 --- a/docs/intro/install.txt +++ b/docs/intro/install.txt @@ -1,10 +1,8 @@ -.. _intro-install: - Quick install guide =================== Before you can use Django, you'll need to get it installed. We have a -:ref:`complete installation guide <topics-install>` that covers all the +:doc:`complete installation guide </topics/install>` that covers all the possibilities; this guide will guide you to a simple, minimal installation that'll work while you walk through the introduction. @@ -12,9 +10,9 @@ Install Python -------------- Being a Python Web framework, Django requires Python. It works with any Python -version from 2.4 to 2.6 (due to backwards +version from 2.4 to 2.7 (due to backwards incompatibilities in Python 3.0, Django does not currently work with -Python 3.0; see :ref:`the Django FAQ <faq-install>` for more +Python 3.0; see :doc:`the Django FAQ </faq/install>` for more information on supported Python versions and the 3.0 transition), but we recommend installing Python 2.5 or later. If you do so, you won't need to set up a database just yet: Python 2.5 or later includes a lightweight database called SQLite_. .. _sqlite: http://sqlite.org/ @@ -25,17 +23,17 @@ probably already have it installed. .. admonition:: Django on Jython If you use Jython_ (a Python implementation for the Java platform), you'll - need to follow a few additional steps. See :ref:`howto-jython` for details. + need to follow a few additional steps. See :doc:`/howto/jython` for details. .. _jython: http://www.jython.org/ You can verify that Python's installed by typing ``python`` from your shell; you should see something like:: - Python 2.5.1 (r251:54863, Jan 17 2008, 19:35:17) + Python 2.5.1 (r251:54863, Jan 17 2008, 19:35:17) [GCC 4.0.1 (Apple Inc. build 5465)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> - + Set up a database ----------------- @@ -57,18 +55,18 @@ Install Django You've got three easy options to install Django: - * Install a version of Django :ref:`provided by your operating system - distribution <misc-distributions>`. This is the quickest option for those + * Install a version of Django :doc:`provided by your operating system + distribution </misc/distributions>`. This is the quickest option for those who have operating systems that distribute Django. * :ref:`Install an official release <installing-official-release>`. This is the best approach for users who want a stable version number and aren't concerned about running a slightly older version of Django. - + * :ref:`Install the latest development version <installing-development-version>`. This is best for users who want the latest-and-greatest features and aren't afraid of running brand-new code. - + .. warning:: If you do either of the first two steps, keep an eye out for parts of the @@ -79,7 +77,7 @@ You've got three easy options to install Django: That's it! ---------- -That's it -- you can now :ref:`move onto the tutorial <intro-tutorial01>`. +That's it -- you can now :doc:`move onto the tutorial </intro/tutorial01>`. diff --git a/docs/intro/overview.txt b/docs/intro/overview.txt index 594c9fe582..0c47e59e14 100644 --- a/docs/intro/overview.txt +++ b/docs/intro/overview.txt @@ -1,5 +1,3 @@ -.. _intro-overview: - ================== Django at a glance ================== @@ -11,8 +9,8 @@ overview of how to write a database-driven Web app with Django. The goal of this document is to give you enough technical specifics to understand how Django works, but this isn't intended to be a tutorial or reference -- but we've got both! When you're ready to start a project, you can -:ref:`start with the tutorial <intro-tutorial01>` or :ref:`dive right into more -detailed documentation <topics-index>`. +:doc:`start with the tutorial </intro/tutorial01>` or :doc:`dive right into more +detailed documentation </topics/index>`. Design your model ================= @@ -21,7 +19,7 @@ Although you can use Django without a database, it comes with an object-relational mapper in which you describe your database layout in Python code. -The :ref:`data-model syntax <topics-db-models>` offers many rich ways of +The :doc:`data-model syntax </topics/db/models>` offers many rich ways of representing your models -- so far, it's been solving two years' worth of database-schema problems. Here's a quick example:: @@ -56,7 +54,7 @@ tables in your database for whichever tables don't already exist. Enjoy the free API ================== -With that, you've got a free, and rich, :ref:`Python API <topics-db-queries>` to +With that, you've got a free, and rich, :doc:`Python API </topics/db/queries>` to access your data. The API is created on the fly, no code generation necessary:: >>> from mysite.models import Reporter, Article @@ -131,7 +129,7 @@ A dynamic admin interface: it's not just scaffolding -- it's the whole house ============================================================================ Once your models are defined, Django can automatically create a professional, -production ready :ref:`administrative interface <ref-contrib-admin>` -- a Web +production ready :doc:`administrative interface </ref/contrib/admin/index>` -- a Web site that lets authenticated users add, change and delete objects. It's as easy as registering your model in the admin site:: @@ -168,8 +166,8 @@ A clean, elegant URL scheme is an important detail in a high-quality Web application. Django encourages beautiful URL design and doesn't put any cruft in URLs, like ``.php`` or ``.asp``. -To design URLs for an app, you create a Python module called a :ref:`URLconf -<topics-http-urls>`. A table of contents for your app, it contains a simple mapping +To design URLs for an app, you create a Python module called a :doc:`URLconf +</topics/http/urls>`. A table of contents for your app, it contains a simple mapping between URL patterns and Python callback functions. URLconfs also serve to decouple URLs from Python code. @@ -216,7 +214,7 @@ and renders the template with the retrieved data. Here's an example view for a_list = Article.objects.filter(pub_date__year=year) return render_to_response('news/year_archive.html', {'year': year, 'article_list': a_list}) -This example uses Django's :ref:`template system <topics-templates>`, which has +This example uses Django's :doc:`template system </topics/templates>`, which has several powerful features but strives to stay simple enough for non-programmers to use. @@ -307,17 +305,17 @@ This is just the surface This has been only a quick overview of Django's functionality. Some more useful features: - * A :ref:`caching framework <topics-cache>` that integrates with memcached + * A :doc:`caching framework </topics/cache>` that integrates with memcached or other backends. - * A :ref:`syndication framework <ref-contrib-syndication>` that makes + * A :doc:`syndication framework </ref/contrib/syndication>` that makes creating RSS and Atom feeds as easy as writing a small Python class. * More sexy automatically-generated admin features -- this overview barely scratched the surface. -The next obvious steps are for you to `download Django`_, read :ref:`the -tutorial <intro-tutorial01>` and join `the community`_. Thanks for your +The next obvious steps are for you to `download Django`_, read :doc:`the +tutorial </intro/tutorial01>` and join `the community`_. Thanks for your interest! .. _download Django: http://www.djangoproject.com/download/ diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index c38fa7d7f5..6045eb111e 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -1,5 +1,3 @@ -.. _intro-tutorial01: - ===================================== Writing your first Django app, part 1 ===================================== @@ -14,7 +12,7 @@ It'll consist of two parts: * A public site that lets people view polls and vote in them. * An admin site that lets you add, change and delete polls. -We'll assume you have :ref:`Django installed <intro-install>` already. You can +We'll assume you have :doc:`Django installed </intro/install>` already. You can tell Django is installed by running the Python interactive interpreter and typing ``import django``. If that command runs successfully, with no errors, Django is installed. @@ -47,8 +45,8 @@ create a ``mysite`` directory in your current directory. you try to run ``django-admin.py startproject``. This is because, on Unix-based systems like OS X, a file must be marked as "executable" before it can be run as a program. To do this, open Terminal.app and navigate (using - the ``cd`` command) to the directory where :ref:`django-admin.py - <ref-django-admin>` is installed, then run the command + the ``cd`` command) to the directory where :doc:`django-admin.py + </ref/django-admin>` is installed, then run the command ``chmod +x django-admin.py``. .. note:: @@ -58,11 +56,11 @@ create a ``mysite`` directory in your current directory. ``django`` (which will conflict with Django itself) or ``test`` (which conflicts with a built-in Python package). -:ref:`django-admin.py <ref-django-admin>` should be on your system path if you +:doc:`django-admin.py </ref/django-admin>` should be on your system path if you installed Django via ``python setup.py``. If it's not on your path, you can find it in ``site-packages/django/bin``, where ```site-packages``` is a directory -within your Python installation. Consider symlinking to :ref:`django-admin.py -<ref-django-admin>` from some place on your path, such as +within your Python installation. Consider symlinking to :doc:`django-admin.py +</ref/django-admin>` from some place on your path, such as :file:`/usr/local/bin`. .. admonition:: Where should this code live? @@ -93,14 +91,14 @@ These files are: * :file:`manage.py`: A command-line utility that lets you interact with this Django project in various ways. You can read all the details about - :file:`manage.py` in :ref:`ref-django-admin`. + :file:`manage.py` in :doc:`/ref/django-admin`. * :file:`settings.py`: Settings/configuration for this Django project. - :ref:`topics-settings` will tell you all about how settings work. + :doc:`/topics/settings` will tell you all about how settings work. * :file:`urls.py`: The URL declarations for this Django project; a "table of contents" of your Django-powered site. You can read more about URLs in - :ref:`topics-http-urls`. + :doc:`/topics/http/urls`. .. _more about packages: http://docs.python.org/tutorial/modules.html#packages @@ -473,7 +471,7 @@ added to your project since the last time you ran syncdb. :djadmin:`syncdb` can be called as often as you like, and it will only ever create the tables that don't exist. -Read the :ref:`django-admin.py documentation <ref-django-admin>` for full +Read the :doc:`django-admin.py documentation </ref/django-admin>` for full information on what the ``manage.py`` utility can do. Playing with the API @@ -508,10 +506,10 @@ things: set the ``DJANGO_SETTINGS_MODULE`` environment variable to ``mysite.settings``. - For more information on all of this, see the :ref:`django-admin.py - documentation <ref-django-admin>`. + For more information on all of this, see the :doc:`django-admin.py + documentation </ref/django-admin>`. -Once you're in the shell, explore the :ref:`database API <topics-db-queries>`:: +Once you're in the shell, explore the :doc:`database API </topics/db/queries>`:: >>> from mysite.polls.models import Poll, Choice # Import the model classes we just wrote. @@ -570,8 +568,8 @@ of this object. Let's fix that by editing the polls model (in the models and don't see any change in how they're represented, you're most likely using an old version of Django. (This version of the tutorial is written for the latest development version of Django.) If you're using a - Subversion checkout of Django's development version (see :ref:`the - installation docs <topics-install>` for more information), you shouldn't have + Subversion checkout of Django's development version (see :doc:`the + installation docs </topics/install>` for more information), you shouldn't have any problems. If you want to stick with an older version of Django, you'll want to switch @@ -693,9 +691,9 @@ Save these changes and start a new Python interactive shell by running >>> c = p.choice_set.filter(choice__startswith='Just hacking') >>> c.delete() -For more information on model relations, see :ref:`Accessing related objects -<ref-models-relations>`. For full details on the database API, see our -:ref:`Database API reference <topics-db-queries>`. +For more information on model relations, see :doc:`Accessing related objects +</ref/models/relations>`. For full details on the database API, see our +:doc:`Database API reference </topics/db/queries>`. -When you're comfortable with the API, read :ref:`part 2 of this tutorial -<intro-tutorial02>` to get Django's automatic admin working. +When you're comfortable with the API, read :doc:`part 2 of this tutorial +</intro/tutorial02>` to get Django's automatic admin working. diff --git a/docs/intro/tutorial02.txt b/docs/intro/tutorial02.txt index a7ab158faa..fcdb812c81 100644 --- a/docs/intro/tutorial02.txt +++ b/docs/intro/tutorial02.txt @@ -1,10 +1,8 @@ -.. _intro-tutorial02: - ===================================== Writing your first Django app, part 2 ===================================== -This tutorial begins where :ref:`Tutorial 1 <intro-tutorial01>` left off. We're +This tutorial begins where :doc:`Tutorial 1 </intro/tutorial01>` left off. We're continuing the Web-poll application and will focus on Django's automatically-generated admin site. @@ -426,7 +424,7 @@ Then, just edit the file and replace the generic Django text with your own site's name as you see fit. This template file contains lots of text like ``{% block branding %}`` -and ``{{ title }}. The ``{%`` and ``{{`` tags are part of Django's +and ``{{ title }}``. The ``{%`` and ``{{`` tags are part of Django's template language. When Django renders ``admin/base_site.html``, this template language will be evaluated to produce the final HTML page. Don't worry if you can't make any sense of the template right now -- @@ -463,5 +461,5 @@ object-specific admin pages in whatever way you think is best. Again, don't worry if you can't understand the template language -- we'll cover that in more detail in Tutorial 3. -When you're comfortable with the admin site, read :ref:`part 3 of this tutorial -<intro-tutorial03>` to start working on public poll views. +When you're comfortable with the admin site, read :doc:`part 3 of this tutorial +</intro/tutorial03>` to start working on public poll views. diff --git a/docs/intro/tutorial03.txt b/docs/intro/tutorial03.txt index 0e09693778..1865b1bd5c 100644 --- a/docs/intro/tutorial03.txt +++ b/docs/intro/tutorial03.txt @@ -1,10 +1,8 @@ -.. _intro-tutorial03: - ===================================== Writing your first Django app, part 3 ===================================== -This tutorial begins where :ref:`Tutorial 2 <intro-tutorial02>` left off. We're +This tutorial begins where :doc:`Tutorial 2 </intro/tutorial02>` left off. We're continuing the Web-poll application and will focus on creating the public interface -- "views." @@ -68,8 +66,8 @@ arbitrary keyword arguments from the dictionary (an optional third item in the tuple). For more on :class:`~django.http.HttpRequest` objects, see the -:ref:`ref-request-response`. For more details on URLconfs, see the -:ref:`topics-http-urls`. +:doc:`/ref/request-response`. For more details on URLconfs, see the +:doc:`/topics/http/urls`. When you ran ``django-admin.py startproject mysite`` at the beginning of Tutorial 1, it created a default URLconf in ``mysite/urls.py``. It also @@ -205,7 +203,7 @@ you want, using whatever Python libraries you want. All Django wants is that :class:`~django.http.HttpResponse`. Or an exception. Because it's convenient, let's use Django's own database API, which we covered -in :ref:`Tutorial 1 <intro-tutorial01>`. Here's one stab at the ``index()`` +in :doc:`Tutorial 1 </intro/tutorial01>`. Here's one stab at the ``index()`` view, which displays the latest 5 poll questions in the system, separated by commas, according to publication date:: @@ -425,7 +423,7 @@ Method-calling happens in the ``{% for %}`` loop: ``poll.choice_set.all`` is interpreted as the Python code ``poll.choice_set.all()``, which returns an iterable of Choice objects and is suitable for use in the ``{% for %}`` tag. -See the :ref:`template guide <topics-templates>` for more about templates. +See the :doc:`template guide </topics/templates>` for more about templates. Simplifying the URLconfs ======================== @@ -514,5 +512,5 @@ under "/content/polls/", or any other URL root, and the app will still work. All the poll app cares about is its relative URLs, not its absolute URLs. -When you're comfortable with writing views, read :ref:`part 4 of this tutorial -<intro-tutorial04>` to learn about simple form processing and generic views. +When you're comfortable with writing views, read :doc:`part 4 of this tutorial +</intro/tutorial04>` to learn about simple form processing and generic views. diff --git a/docs/intro/tutorial04.txt b/docs/intro/tutorial04.txt index ee3a3b2045..a7a9aaea33 100644 --- a/docs/intro/tutorial04.txt +++ b/docs/intro/tutorial04.txt @@ -1,10 +1,8 @@ -.. _intro-tutorial04: - ===================================== Writing your first Django app, part 4 ===================================== -This tutorial begins where :ref:`Tutorial 3 <intro-tutorial03>` left off. We're +This tutorial begins where :doc:`Tutorial 3 </intro/tutorial03>` left off. We're continuing the Web-poll application and will focus on simple form processing and cutting down our code. @@ -70,7 +68,7 @@ The details of how this works are explained in the documentation for :ref:`RequestContext <subclassing-context-requestcontext>`. Now, let's create a Django view that handles the submitted data and does -something with it. Remember, in :ref:`Tutorial 3 <intro-tutorial03>`, we +something with it. Remember, in :doc:`Tutorial 3 </intro/tutorial03>`, we created a URLconf for the polls application that includes this line:: (r'^(?P<poll_id>\d+)/vote/$', 'vote'), @@ -149,7 +147,7 @@ This code includes a few things we haven't covered yet in this tutorial: As mentioned in Tutorial 3, ``request`` is a :class:`~django.http.HttpRequest` object. For more on :class:`~django.http.HttpRequest` objects, see the -:ref:`request and response documentation <ref-request-response>`. +:doc:`request and response documentation </ref/request-response>`. After somebody votes in a poll, the ``vote()`` view redirects to the results page for the poll. Let's write that view:: @@ -158,8 +156,8 @@ page for the poll. Let's write that view:: p = get_object_or_404(Poll, pk=poll_id) return render_to_response('polls/results.html', {'poll': p}) -This is almost exactly the same as the ``detail()`` view from :ref:`Tutorial 3 -<intro-tutorial03>`. The only difference is the template name. We'll fix this +This is almost exactly the same as the ``detail()`` view from :doc:`Tutorial 3 +</intro/tutorial03>`. The only difference is the template name. We'll fix this redundancy later. Now, create a ``results.html`` template: @@ -183,7 +181,7 @@ without having chosen a choice, you should see the error message. Use generic views: Less code is better ====================================== -The ``detail()`` (from :ref:`Tutorial 3 <intro-tutorial03>`) and ``results()`` +The ``detail()`` (from :doc:`Tutorial 3 </intro/tutorial03>`) and ``results()`` views are stupidly simple -- and, as mentioned above, redundant. The ``index()`` view (also from Tutorial 3), which displays a list of polls, is similar. @@ -328,8 +326,8 @@ are) used multiple times -- but we can use the name we've given:: Run the server, and use your new polling app based on generic views. -For full details on generic views, see the :ref:`generic views documentation -<topics-http-generic-views>`. +For full details on generic views, see the :doc:`generic views documentation +</topics/http/generic-views>`. Coming soon =========== @@ -344,5 +342,5 @@ will cover: * Advanced admin features: Permissions * Advanced admin features: Custom JavaScript -In the meantime, you might want to check out some pointers on :ref:`where to go -from here <intro-whatsnext>` +In the meantime, you might want to check out some pointers on :doc:`where to go +from here </intro/whatsnext>` diff --git a/docs/intro/whatsnext.txt b/docs/intro/whatsnext.txt index 0949b2299e..fe385ffd9a 100644 --- a/docs/intro/whatsnext.txt +++ b/docs/intro/whatsnext.txt @@ -1,10 +1,8 @@ -.. _intro-whatsnext: - ================= What to read next ================= -So you've read all the :ref:`introductory material <intro-index>` and have +So you've read all the :doc:`introductory material </intro/index>` and have decided you'd like to keep using Django. We've only just scratched the surface with this intro (in fact, if you've read every single word you've still read less than 10% of the overall documentation). @@ -37,15 +35,15 @@ How the documentation is organized Django's main documentation is broken up into "chunks" designed to fill different needs: - * The :ref:`introductory material <intro-index>` is designed for people new + * The :doc:`introductory material </intro/index>` is designed for people new to Django -- or to web development in general. It doesn't cover anything in depth, but instead gives a high-level overview of how developing in Django "feels". - * The :ref:`topic guides <topics-index>`, on the other hand, dive deep into + * The :doc:`topic guides </topics/index>`, on the other hand, dive deep into individual parts of Django. There are complete guides to Django's - :ref:`model system <topics-db-index>`, :ref:`template engine - <topics-templates>`, :ref:`forms framework <topics-forms-index>`, and much + :doc:`model system </topics/db/index>`, :doc:`template engine + </topics/templates>`, :doc:`forms framework </topics/forms/index>`, and much more. This is probably where you'll want to spend most of your time; if you work @@ -53,27 +51,27 @@ different needs: everything there is to know about Django. * Web development is often broad, not deep -- problems span many domains. - We've written a set of :ref:`how-to guides <howto-index>` that answer + We've written a set of :doc:`how-to guides </howto/index>` that answer common "How do I ...?" questions. Here you'll find information about - :ref:`generating PDFs with Django <howto-outputting-pdf>`, :ref:`writing - custom template tags <howto-custom-template-tags>`, and more. + :doc:`generating PDFs with Django </howto/outputting-pdf>`, :doc:`writing + custom template tags </howto/custom-template-tags>`, and more. - Answers to really common questions can also be found in the :ref:`FAQ - <faq-index>`. + Answers to really common questions can also be found in the :doc:`FAQ + </faq/index>`. * The guides and how-to's don't cover every single class, function, and method available in Django -- that would be overwhelming when you're trying to learn. Instead, details about individual classes, functions, - methods, and modules are kept in the :ref:`reference <ref-index>`. This is + methods, and modules are kept in the :doc:`reference </ref/index>`. This is where you'll turn to find the details of a particular function or whathaveyou. * Finally, there's some "specialized" documentation not usually relevant to - most developers. This includes the :ref:`release notes <releases-index>`, - :ref:`documentation of obsolete features <obsolete-index>`, - :ref:`internals documentation <internals-index>` for those who want to add - code to Django itself, and a :ref:`few other things that simply don't fit - elsewhere <misc-index>`. + most developers. This includes the :doc:`release notes </releases/index>`, + :doc:`documentation of obsolete features </obsolete/index>`, + :doc:`internals documentation </internals/index>` for those who want to add + code to Django itself, and a :doc:`few other things that simply don't fit + elsewhere </misc/index>`. How documentation is updated @@ -187,11 +185,10 @@ You can get a local copy of the HTML documentation following a few easy steps: * The HTML documentation will be placed in ``docs/_build/html``. -.. warning:: +.. note:: - At the time of this writing, Django's using a version of Sphinx not - yet released, so you'll currently need to install Sphinx from the - source. We'll fix this shortly. + Generation of the Django documentation will work with Sphinx version 0.6 + or newer, but we recommend going straight to Sphinx 1.0.2 or newer. __ http://sphinx.pocoo.org/ __ http://www.gnu.org/software/make/ |