Qué leer después¶
De modo que usted ha leído todo el material introductorio y ha decidido que le gustaría seguir usando Django. Sólo hemos arañado la superficie con esta introducción (de hecho, si usted ha leído cada palabra, usted ha leído un 5% de la totalidad de la documentación).
Ahora ¿qué sigue?
Bueno, siempre hemos sido grandes fans de aprender haciendo. En este punto, usted debe saber lo suficiente como para iniciar un proyecto por su cuenta y empezar a divertirse. Conforme necesite aprender nuevos trucos, vuelva a la documentación.
Nos hemos esforzado mucho en 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 más sobre cómo funciona la documentación para que pueda sacar el máximo provecho de ella.
(Sí, se trata de documentación sobre la documentación. Tenga la seguridad de que no tenemos planes de escribir un documento de cómo leer el documento sobre la documentación.)
Buscando documentación¶
Django tiene mucha documentación, casi 450,000 mil palabras y contando, por lo que encontrar lo que necesita a veces puede ser complicado. Algunos buenos lugares para empezar son la Página de Búsqueda y el Índice.
O ¡simplemente usted puede echar un vistazo!
Cómo está organizada la documentación¶
La documentación principal de Django se divide en «trozos» diseñados para atender los diferentes requerimientos:
El material introductorio está diseñado para los principiantes en Django – o en el desarrollo web en general. No trata nada en profundidad, sino que da una introducción de alto nivel de cómo «se siente» desarrollar en Django.
Por otro lado, las guías temáticas profundizan en las secciones individuales de Django. Hay guías completas para el sistema de modelos de Django, motor de plantillas, framework de formularios y mucho más.
Aquí es probablemente donde usted querrá pasar la mayor parte de su tiempo; si usted avanza en el estudio de estas guías debe salir sabiendo casi todo lo que hay que saber acerca de Django.
El desarrollo web suele ser amplio, pero no profundo; los problemas abarcan muchos ámbitos. Hemos escrito un conjunto de guías paso a paso que responden las preguntas comúnes tipo «¿Cómo puedo…?». Aquí encontrará información sobre cómo Crear PDFs con Django, escribir etiquetas de plantilla personalizadas y más.
También se pueden encontrar respuestas a preguntas muy comunes en el FAQ.
Las guías y tutoriales paso a paso no abarcan cada clase, función y método disponible en Django, eso sería abrumador cuando usted está tratando de aprender. En su lugar, la información sobre las clases, funciones, métodos y módulos individuales se guardan en la referencia. Aquí es donde buscará la información sobre una función en particular o lo que usted necesite.
Si usted está interesado en la implementación de un proyecto para el uso público, nuestra documentación tienen varias guías para diversas configuraciones de implementación, así como una lista de implementación para algunas cosas que usted tendrá que considerar.
Por último, hay documentación «especializada» que no suele ser relevante para la mayoría de los desarrolladores. Esto incluye las notas de la versión y la documentación de los internos para aquellos que quieren añadir código a Django, y otras cosas que simplemente no encajan en otros lugares.
Cómo se mejora la documentación¶
Así como el código base de Django se desarrolla y mejora día a día, nuestra documentación está mejorando constantemente. Mejoramos la documentación por varias razones:
- Para hacer correcciones de contenido tales como correcciones gramaticales y de errores tipográficos.
- Para añadir información y/o ejemplos a las secciones existentes que necesitan ser ampliadas.
- Para documentar las funcionalidades de Django que aún no están documentadas. (La lista de dichas funcionalidades se reduce, sin embargo, existe a pesar de ello.)
- Para agregar la documentación de las nuevas características a medida que estas se añaden o cuando cambian las APIs de Django o los comportamientos.
La documentación de Django se guarda en el mismo sistema de gestión de código fuente como su código. Está en el directorio docs de nuestro repositorio Git. Cada documento online es un archivo de texto separado en el repositorio.
Dónde conseguirla¶
Usted puede leer la documentación de Django de varias maneras. Las formas de leer la documentación están en orden de preferencia:
En la Web¶
The most recent version of the Django documentation lives at https://docs.djangoproject.com/en/dev/. These HTML pages are generated automatically from the text files in source control. That means they reflect the «latest and greatest» in Django – they include the very latest corrections and additions, and they discuss the latest Django features, which may only be available to users of the Django development version. (See Diferencias entre versiones below.)
Le animamos a ayudar a mejorar la documentación mediante la presentación de cambios, correcciones y sugerencias en el ticket system. Los desarrolladores de Django monitorean activamente el sistema de tickets y utilizan sus comentarios y sugerencias para mejorar la documentación para todo el mundo.
Sin embargo, tenga en cuenta que las tickets deberían estar relacionadas expresamente con la documentación, en lugar de hacer preguntas generales de soporte técnico. Si usted necesita ayuda con su configuración particular de Django, pruebe en su lugar la lista de correos de los django-users o en el canal de chat #django IRC.
En texto sin formato¶
Usted puede leer la documentación de Django en texto plano, para su lectura sin conexión a la red o simplemente por comodidad.
If you’re using an official release of Django, the zipped package (tarball) of
the code includes a docs/ directory, which contains all the documentation
for that release.
If you’re using the development version of Django (aka the master branch), the
docs/ directory contains all of the documentation. You can update your
Git checkout to get the latest changes.
Una forma de baja tecnología de aprovechar la documentación de textos es mediante el uso de la utilidad grep de Unix para buscar una expresión en toda la documentación. Por ejemplo, esta le mostrará cada referencia de la expresión «max_length» en cualquier documento de Django:
$ grep -r max_length /path/to/django/docs/
...\> grep -r max_length \path\to\django\docs\
Localmente como HTML¶
Usted puede obtener una copia local de la documentación HTML siguiendo unos sencillos pasos:
La documentación de Django utiliza un sistema llamado Sphinx para convertir el texto plano en HTML. Usted tendrá que instalar Sphinx bien sea descargando e instalando el paquete desde el sitio web de Sphinx o con
pip:$ pip install Sphinx...\> pip install SphinxLuego, sólo tiene que utilizar el
Makefileincluido para convertir la documentación en HTML:$ cd path/to/django/docs $ make html
Usted tendrá que instalar GNU Make para esto.
Si está en Windows puede utilizar alternativamente el archivo batch incluido:
cd path\to\django\docs make.bat htmlLa documentación HTML se ubicará en
docs/_build/html.
Diferencias entre versiones¶
The text documentation in the master branch of the Git repository contains the «latest and greatest» changes and additions. These changes include documentation of new features targeted for Django’s next feature release. For that reason, it’s worth pointing out our policy to highlight recent changes and additions to Django.
Seguimos esta política:
- The development documentation at https://docs.djangoproject.com/en/dev/ is from the master branch. These docs correspond to the latest feature release, plus whatever features have been added/changed in the framework since then.
- As we add features to Django’s development version, we update the documentation in the same Git commit transaction.
- To distinguish feature changes/additions in the docs, we use the phrase: «New in Django Development version» for the version of Django that hasn’t been released yet, or «New in version X.Y» for released versions.
- Las correcciones y mejoras de la documentación pueden ser portadas a la última rama de la versión, según el criterio del committer, sin embargo, una vez que una versión de Django ya no es compatible, esa versión de la documentación no recibirá actualizaciones adicionales.
- The main documentation Web page includes links to documentation for previous versions. Be sure you are using the version of the docs corresponding to the version of Django you are using!
