Qué leer a continuación¶
Bien, ya leíste el material de introducción y decidiste que querés seguir usando Django Esta introducción sólo cubre Django de manera superficial (de hecho, si leíste toda y cada una de las palabras de este material, es alrededor de un 5% del total de la documentación).
Cómo seguir?
Bueno, siempre hemos sido grandes fans de aprender haciendo. En este punto deberías saber lo suficiente para empezar un proyecto por tu cuenta y empezar a probar. A medida que vayas necesitando trucos nuevos, podés volver a la documentación.
Hemos puesto un esfuerzo importante para hacer que la documentación de Django sea útil, fácil de leer y tan completa como sea posible. El resto de este documento explica un más sobre cómo funciona la documentación para que puedas aprovecharla al máximo.
(Sí, esta documentación es sobre la documentación. Podés quedarte tranquilo que no tenemos planes de escribir un documento sobre cómo leer el documento sobre la documentación).
Encontrando documentación¶
Django tiene mucha documentación – casi 450.000 palabras y contando –, entonces encontrar lo que uno necesita puede resultar complicado a veces. Un par de buenos lugares para empezar son la búsqueda y el índice general.
O navegarla!
Cómo se organiza la documentación¶
La documentación principal de Django se divide en “chunks”, diseñados para cubrir diferentes necesidades:
El material introductorio está diseñado para la gente nueva en Django – o nueva en desarrollo web en general. No cubre nada en profundidad, pero en cambio da un vistazo general a cómo se siente desarrollar en Django.
Las guías temáticas, por otro lado, dan un detalle más profundo de las partes individuales de Django. Hay guías completas sobre el sistema de modelos, el motor de templates, el framework de forms, y mucho más.
Aquí es donde probablemente pases la mayor parte del tiempo; si le encontrás la vuelta a estas guías deberías salir sabiendo prácticamente todo lo que hay que saber de Django.
El desarrollo web se extiende en general a lo ancho, no en profundo – los problemas se extienden a muchos dominios. Hemos escrito un conjunto de how-to guides que responden las preguntas comunes de la forma “How do I ...?”. Allí encontrarás información sobre generar PDFs con Django, escribir template tags propios, y más.
Respuestas a preguntas realmente comunes se pueden encontrar en las FAQ.
Estas guías y how-to’s no cubren toda clase, función y método disponible en Django – eso sería demasiado cuando uno está intentando aprender. En vez de eso, los detalles de clases, funciones, métodos y módulos individuales se mantienen en la referencia. Allí es donde deberías dirigirte para encontrar los detalles particulares de una función o cualquier otra cosa que necesites.
Si estás interesado en deployar un proyecto para su uso público, nuestra documentación tiene varias guías para distintas configuraciones, así como una checklist para algunos puntos a tener en cuenta.
Finalmente, hay documentación “especializada” que no es relevante para la mayoría de los desarrolladores. Esto incluye release notes y internals documentation para aquellos que quieren contribuir código a Django mismo, y algunas otras cosas que no encajan en las demás secciones.
Cómo se actualiza la documentación¶
Así como el código base de Django se desarrolla y mejora de forma diaria, la documentación se mejora continuamente. Mejoramos la documentación por varias razones:
Para hacer correcciones de contenido, tales como correcciones de tipeo o gramaticales.
Para agregar información y/o ejemplos a secciones existentes que lo necesiten.
Para documentar características de Django que todavía no lo estuvieran (esa lista de acorta, pero todavía hay cosas por documentar).
Para agregar documentación de características nuevas a medida que éstas se agregan, o a medida que el comportamiento de las APIs de Django cambia.
La documentación de Django se mantiene en el mismo sistema de control de versiones que su código. Vive en el directorio docs de nuestro repositorio Git. Cada documento es un archivo de texto separado en el repositorio.
Dónde obtenerla¶
Podés leer la documentación de Django en varias formas. En orden de preferencia:
En la web.¶
La versión más reciente de Django vive en https://docs.djangoproject.com/en/dev/. Estas páginas HTML se generan automáticamente a partir de los archivos de texto en el repositorio. Esto significa que reflejan lo “último” en Django – incluyen las correcciones y adiciones más recientes, y discuten las más recientes características de Django, que puede que sólo estén disponibles a usuarios de la versión en desarrollo de Django (ver “Diferencias entre versiones” más abajo).
Te alentamos a ayudar mejorar la documentación, enviando cambios, correcciones y sugerencias en el sistema de tickets. Los desarrolladores de Django monitorean activamente el sistema de tickets y usan el feedback para mejorar la documentación para todos.
Notar sin embargo que los tickets deben ser relacionados explícitamente a la documentación, en lugar de hacer preguntas de soporte. Si necesitás ayuda con algo particular del uso de Django, probá en vez django-users mailing list o el canal de #django en IRC.
En texto plano¶
Para leer offline, o por conveniencia, se puede leer la documentación de Django en texto plano.
Si estás usando un release oficial de Django, notar que el paquete zip (tarball) del código incluye un directorio docs/, que contiene toda la documentación de ese release.
Si estás usando una versión en desarrollo de Django (aka “trunk”), notar que el directorio docs/ contiene toda la documentación. Podés actualizar tu checkout para recibir los últimos cambios.
Una manera low-tech de aprovechar la documentación en texto es usando la utilidad grep de Unix para buscar una frase en toda la documentación. Por ejemplo, esto va a mostrar toda mención de la frase “max_length” en cualquier documento de Django:
$ grep -r max_length /path/to/django/docs/
Como HTML, localmente¶
Se puede obtener una copia del HTML de la documentación siguiendo unos simples pasos:
La documentación de Django usa un sistema llamado Sphinx para converitr de texto plano a HTML. Vas a necesitar instalar Sphinx ya sea bajando e instalando el paquete del sitio web de Sphinx, o con pip:
$ pip install Sphinx
Luego, basta usar el archivo Makefile incluido para generar la documentación en HTML:
$ cd path/to/django/docs $ make html
Vas a necesitar GNU Make instalado para esto.
Si estás en Windows, podés alternativamente usar el archivo batch incluido:
cd path\to\django\docs make.bat html
La documentación HTML se ubicará en docs/_build/html.
Nota
La generación de la documentación de Django funciona con Sphinx 0.6 o mayor, pero recomendamos usar 1.0.2 o más nueva.
Diferencias entre versiones¶
Como se mencionó antes, la documentación en texto en el repositorio Git contiene “lo último” en cambios y adiciones. Estos cambios a veces incluyen documentación de nuevas características que se agregan en la version en desarrollo de Django – la versión Git (“trunk”) de Django. Por esta razón vale la pena mencionar nuestra política de mantener la documentación al día para las distintas versiones del framework.
Seguimos esta política:
La documentación primaria en djangoproject.com es la version HTML de lo último en Git. Esta documentación se corresponde con la última release oficial de Django, además de las características que se agregaron/cambiaron desde el último release.
A medida que se agregan características a la versión en desarrollo de Django, tratamos de mantener la documentación actualizada en el mismo commit de Git.
Para distinguir cambios/adiciones en la documentación, se usa la frase “New in version X.Y”, donde X.Y es la próxima versión a ser liberada (es decir, la versión en desarrollo).
Correcciones y mejoras a la documentación se portan a las versiones anteriores a discreción del committer; sin embargo, una vez que la versión de Django no se soporta más, la documentación de esa versión no recibe más actualizaciones.
La pagína principal de la documentación en la web incluye links a la documentación de todas las versiones anteriores. Fijate de chequear que la versión de la documentación sea la que corresponde a la versión de Django que estás usando!