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).
\nAhora ¿Qué sigue?
\nBueno, 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.
\nNos 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.
\n(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.)
\nDjango 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.
\no ¡Simplemente usted puede echar un vistazo!
\nLa documentación principal de Django se divide en «trozos» diseñados para atender los diferentes requerimientos:
\nEl :doc:`material introductorio </intro/index> ` 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 :doc: sistema de modelos de Django </topics/db/index> , :doc: motor de plantillas </topics/templates> `, :doc:`framework de formularios </topics/forms/index> ` y mucho más.
\nAquí 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.
\nEl desarrollo web suele ser amplio, pero no profundo; los problemas abarcan muchos ámbitos. Hemos escrito un conjunto de: doc: guías pasp a paso </howto/index> ` que responden las preguntas comúnes tipo «¿Cómo puedo…?». Aquí encontrará información sobre cómo :doc:`Crear PDFs con Django </howto/outputting-pdf> `, :doc:`escribir etiquetas de plantilla personalizadas </howto/custom-template-tags> y más.
\nTambién se pueden encontrar respuestas a preguntas muy comunes en el FAQ.
\nLas 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, nuestros documentos tienen varias guías </howto/deployment/index> ` para diversas configuraciones de implementación, así como una :doc: lista de implementación </howto/deployment/checklist> ` 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 para aquellos que quieren añadir código a Django, y :doc:` otras cosas que simplemente no encajan en otros lugares </misc/index>`.
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:
\nPara 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.
\nUsted puede leer la documentación de Django de varias maneras. Las formas de leer la documentación están en orden de preferencia:
\nLa versión más reciente de la documentación de Django se encuentra en https://docs.djangoproject.com/en/dev/. Estas páginas HTML se generan automáticamente a partir de los archivos de texto en el control de código fuente. Eso significa que muestran lo «último y lo mejor» de Django, ellas incluyen las últimas correcciones y adiciones, y abordan las últimas funcionalidades de Django que sólo podrían estar disponibles para los usuarios de la versión de desarrollo de Django. (Consulte «Las diferencias entre las versiones» a continuación.)
\nLe 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.
\nSin 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.
\nUsted puede leer la documentación de Django en texto plano, para su lectura sin conexión a la red o simplemente por comodidad.
\nSi está usando una versión oficial de Django, tenga en cuenta que el paquete comprimido (tarball) del código incluye un directorio docs/ que contiene toda la documentación de esa versión.
Si está utilizando la versión de desarrollo de Django (también conocida como «trunk»), tenga en cuenta que el directorio docs/ contiene toda la documentación. Puede actualizar su git checkout para recibir las últimas novedades.
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/\nUsted puede obtener una copia local de la documentación HTML siguiendo unos sencillos pasos:
\nLa 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\nLuego, sólo tiene que utilizar el `` Makefile`` incluido para convertir la documentación en HTML:
\n$ cd path/to/django/docs\n$ make html\nUsted tendrá que instalar GNU Make para esto.
\nSi está en Windows puede utilizar alternativamente el archivo batch incluido:
\ncd path\\to\\django\\docs\nmake.bat html\nLa documentación HTML se ubicará en “”docs/_build/html””.
Como se mencionó anteriormente, la documentación de textos en nuestro repositorio Git contiene los «últimos y mejores» cambios y adiciones. Estos cambios suelen incluir la documentación de las nuevas funcionalidades que se añaden en la versión de desarrollo de Django; la versión Git («trunk») de Django. Por esa razón, vale la pena señalar nuestra política de continuar la documentación para las distintas versiones del framework.
\nSeguimos esta política:
\nLa documentación principal en djangoproject.com es una versión HTML de los últimos documentos en Git. Estos documentos corresponden siempre a la versión oficial más reciente de Django y cualquier característica que hayamos añadido y/o cambiado en el framework a partir de la última versión.
A medida que añadimos funcionalidades a la versión de desarrollo de Django, tratamos de actualizar la documentación en la misma transacción de commit de Git.
Para distinguir los cambios y adiciones de funcionalidades en la documentación, usamos la frase: «New in version X.Y», siendo X.Y la próxima versión de lanzamiento (por lo tanto, la que está siendo desarrollada).
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: ref: ya no es compatible <backwards-compatibility-policy>, esa versión de los documentos no recibirá actualizaciones adicionales.
La página Web de la documentación principal incluye enlaces a la documentación para todas las versiones anteriores. ¡Asegúrese de que está utilizando la versión de los documentos que corresponden a la versión de Django que está utilizando!