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 :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.
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: 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.
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, 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>`.
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¶
La 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.)
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.
Si 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/
As HTML, locally¶
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 SphinxLuego, sólo tiene que utilizar el `` Makefile`` incluido 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¶
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.
Seguimos esta política:
La 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!
