Damos mucha importancia a la consistencia y legibilidad de la documentación. Después de todo, Django se creó en un entorno de periodismo! Así que tratamos nuestra documentación como trataríamos nuestro código: nos esforzamos por mejorarla lo más a menudo posible.
Los cambios en la documentación suelen venir en dos formas:
Mejoras generales: correcciones de errores, mejoras en las explicaciones y escritura más clara con más ejemplos.
Nuevas características: documentación de características que se han agregado al marco desde la última versión.
Esta sección explica cómo los escritores pueden elaborar sus cambios en la documentación de manera lo más útil y menos propensa a errores.
Aunque la documentación de Django está destinada a ser leída como HTML en https://docs.djangoproject.com/, la editamos como una colección de archivos de texto plano escritos en el lenguaje de marcado reStructuredText para máxima flexibilidad.
Trabajamos desde la versión de desarrollo del repositorio porque tiene la documentación más actualizada, al igual que el código más reciente.
También incorporamos correcciones y mejoras en la documentación a la rama de lanzamiento más reciente, según la discreción del merge. Esto es beneficioso para tener los docs de la última versión actualizados y correctos (ver diferencias-entre-versiones-de-doc).
La documentación de Django utiliza el sistema de documentación Sphinx, que a su vez se basa en docutils. La idea básica es que la documentación de texto plano ligeramente formateada se transforme en HTML, PDF y cualquier otro formato de salida.
Sphinx incluye un comando sphinx-build para convertir reStructuredText en otros formatos, por ejemplo, HTML y PDF. Este comando es configurable, pero la documentación de Django incluye un archivo Makefile que proporciona un comando más corto make html.
La documentación está organizada en varias categorías:
Tutoriales guían al lector a través de una serie de pasos para crear algo.
La importancia principal en un tutorial es ayudar al lector a lograr algo útil, preferiblemente lo antes posible, para darles confianza.
Explica la naturaleza del problema que estamos resolviendo, de modo que el lector entienda qué estamos tratando de lograr. No te sientas obligado a comenzar con explicaciones sobre cómo funcionan las cosas - lo que importa es lo que hace el lector, no lo que explicas. Puede ser útil referirte posteriormente a lo que has hecho y explicarlo después.
Guías de temas tienen como objetivo explicar un concepto o tema a un nivel bastante alto.
Enlaza con material de referencia en lugar de repetirlo. Utiliza ejemplos y no tengas miedo de explicar cosas que parezcan muy básicas para ti - puede ser la explicación que alguien más necesita.
Proporcionar contexto de fondo ayuda a un nuevo usuario a conectar el tema con las cosas que ya conoce.
Guías de referencia contienen referencias técnicas para APIs. Describen la funcionalidad del mecanismo interno de Django y instruyen en su uso.
Mantén el material de referencia muy enfocado en el tema. Supone que el lector ya entiende los conceptos básicos involucrados pero necesita saber o recordar cómo hace Django.
Las guías de referencia no son el lugar para la explicación general. Si te encuentras explicando conceptos básicos, puede que desees mover ese material a una guía de temas.
Guías paso a paso son recetas que llevan al lector por pasos en temas clave.
Lo que importa más en una guía paso a paso es lo que un usuario quiere lograr. Una guía paso a paso siempre debe ser orientada hacia el resultado en lugar de enfocarse en los detalles internos de cómo Django implementa lo que se está discutiendo.
Estos guías son más avanzados que las tutoriales y suponen un conocimiento previo sobre cómo funciona Django. Supone que el lector ha seguido los tutoriales y no dudar en referir al lector a la tutoria apropiada en lugar de repetir el mismo material.
Si deseas empezar a contribuir con nuestros docs, obtén la versión de desarrollo de Django desde el repositorio del código fuente (ver instalar-una-versión-de-desarrollo):
$ git clone https://github.com/django/django.git
Si planeas enviar estas modificaciones, podrías encontrar útil hacer un fork del repositorio de Django y clonar este fork en lugar.
Crea y activa un entorno virtual, luego instala las dependencias:
$ python -m venv .venv
$ source .venv/bin/activate
$ python -m pip install -r docs/requirements.txt
Podemos construir el HTML desde el directorio docs:
$ cd docs
$ make html
Tu documentación localmente construida estará accesible en _build/html/index.html y puede ser vista con cualquier navegador web, aunque se mostrará de manera diferente que la documentación en docs.djangoproject.com. Esto está bien. Si tus cambios parecen buenos en tu máquina local, también lo parecerán en el sitio web.
Los archivos fuente son archivos .txt ubicados en el directorio docs/.
Estos archivos están escritos en el lenguaje de marcado reStructuredText. Para aprender el marcado, consulta la referencia de reStructuredText.
Para editar esta página, por ejemplo, editaríamos el archivo docs/internals/contributing/writing-documentation.txt y reconstruiríamos el HTML con make html.
Varias verificaciones ayudan a mantener la calidad de la documentación de Django, incluyendo verificación de ortografía y formato de bloques de código.
Estas verificaciones se ejecutan automáticamente en CI y deben pasar antes de que puedan ser fusionadas las cambios de documentación. También pueden ejecutarse localmente con un solo comando:
$ make check
Este comando ejecuta todas las verificaciones actuales y incluirá cualquier nueva verificación agregada en el futuro.
Antes de que cometas tus docs, es una buena idea ejecutar el corrector ortográfico. Necesitarás instalar sphinxcontrib-spelling primero. Luego desde el directorio docs, ejecuta:
$ make spelling
Los textos traducidos son:
Si encuentras falsos positivos (salida de error que en realidad es correcta), haz una de las siguientes cosas:
Circa las palabras clave o nombres de tecnología con acentos graves dobles (``).
Encuentra sinónimos que el corrector ortográfico reconoce.
Si, y solo si, estás seguro de que la palabra que estás utilizando es correcta - añádelo a docs/spelling_wordlist (por favor mantén la lista en orden alfabético).
Todos los bloques de código Python deben estar formateados utilizando el blacken-docs auto-formatter. Esto se ejecuta automáticamente por el hook pre-commit si está configurado.
La comprobación también puede ejecutarse manualmente: siempre que blacken-docs esté instalado, ejecuta la siguiente orden desde el directorio docs:
$ make black
El formateador informará sobre cualquier problema imprimiendo los mismos en la terminal y reformatará bloques de código donde sea posible.
Los enlaces en la documentación pueden volverse rotos o cambiados de modo que ya no sean el enlace canónico. Sphinx proporciona un constructor que puede comprobar si los enlaces en la documentación están funcionando. Desde el directorio docs, ejecuta:
$ make linkcheck
La salida se imprime en la terminal, pero también se puede encontrar en _build/linkcheck/output.txt y _build/linkcheck/output.json.
Advertencia
La ejecución del comando requiere una conexión a Internet y tarda varios minutos en completarse, porque el comando prueba todos los enlaces que se encuentran en la documentación.
Las entradas con un estado de «funcionando» están bien, aquellas que son «sin comprobar» o «ignoradas» han sido omitidas porque no pueden ser comprobadas o coinciden con reglas de ignorancia en la configuración.
Las entradas con un estado de «rotas» necesitan ser corregidas. Aquellas que tienen un estado de «redirigido» pueden necesitar ser actualizadas para apuntar a la ubicación canónica, por ejemplo, cuando el esquema cambia http:// → https://. En ciertos casos, no queremos actualizar un enlace «redirigido», por ejemplo, una reescritura que siempre apunte a la versión más reciente o estable de la documentación, por ejemplo, /en/stable/ → /en/3.2/.
Cuando se utilizan pronombres en referencia a una persona hipotética, como «un usuario con una cookie de sesión», deben usarse pronombres neutros de género (they/their/them). En lugar de:
él o ella… usa they.
le o a ella… usa them.
su o su… usa their.
his o suyo… use el suyo.
él mismo o ella misma… use ellos mismos.
Intenta evitar usar palabras que minimicen la dificultad involucrada en una tarea o operación, como «fácilmente», «simplemente», «sólo», «meramente», «de manera directa», y así sucesivamente. La experiencia de las personas puede no coincidir con tus expectativas, y pueden frustrarse cuando no encuentren un paso que sea «fácil» o «simple» como se implica que debe ser.
Aquí hay algunas directrices sobre términos estilos comúnmente utilizados a lo largo de la documentación:
Django – cuando se refiere al marco, capitaliza Django. Solo está en minúscula en el código Python y en el logotipo de djangoproject.com.
correo electrónico – sin guión.
HTTP – la pronunciación esperada es «Aitch Tee Tee Pee» y por lo tanto debe precederse con «an» y no con «a».
MySQL, PostgreSQL, SQLite
SQL – cuando se refiere a SQL, la pronunciación esperada debería ser «Ess Queue Ell» y no «secuela». Por lo tanto en una frase como «Devuelve una expresión SQL», «SQL» debe precederse con «an» y no con «a».
Python – cuando se refiere al lenguaje, capitaliza Python.
realizar, personalizar, inicializar, etc. – utiliza el sufijo americano «ize», no «ise».
sobrecargar – es una sola palabra sin guión, tanto como verbo («sobrecargar ese modelo») como sustantivo («crear un sobrecargado»).
la web, framework de la web – no está capitalizado.
sitio web – utiliza una sola palabra, sin mayúsculas.
modelo – no está capitalizado.
plantilla – no está capitalizada.
URLconf – utiliza tres letras mayúsculas, sin espacio antes de «conf».
vista – no está capitalizada.
Estas directrices regulan el formato de nuestra documentación en reST (reStructuredText):
En los títulos de sección, capitaliza solo las palabras iniciales y los nombres propios.
Envuelve la documentación a 80 caracteres de ancho, a menos que un ejemplo de código sea significativamente menos legible cuando se divide en dos líneas, o por otra buena razón.
La cosa principal a tener en cuenta al escribir y editar documentos es que cuanto más marcado semántico puedas agregar, mejor. Así:
Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
No es casi tan útil como:
Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
Esto se debe a que Sphinx generará enlaces propios para el último, lo cual ayuda mucho a los lectores.
Puedes prefijar el objetivo con un ~ (que es una tilde) para obtener solo la «última parte» de ese camino. Así :mod:`~django.contrib.auth` mostrará un enlace con el título «auth».
Utiliza intersphinx para referenciar la documentación de Python y Sphinx.
Agrega .. code-block:: <lang> a bloques literales para que se resalten. Preferirás confiar en el resaltado automático utilizando :: (dos dos puntos). Esto tiene el beneficio de que si el código contiene algún sintaxis inválida, no se resaltarán. Agregar .. code-block:: python, por ejemplo, forzará el resaltado a pesar de la sintaxis inválida.
Para mejorar la legibilidad, utiliza .. admonition:: Título descriptivo en lugar de .. note::. Utiliza estas cajas con moderación.
Utiliza estos estilos de encabezado:
===
One
===
Two
===
Three
-----
Four
~~~~
Five
^^^^
Utiliza :rfc: para referenciar una Solicitud de Comentarios (RFC) y trata de enlazar a la sección relevante si es posible. Por ejemplo, utiliza :rfc:`2324#section-2.3.2` o :rfc:`Texto de enlace personalizado <2324#section-2.3.2>`.
Utiliza :pep: para referenciar una Propuesta de Mejora del Lenguaje Python (PEP) y trata de enlazar a la sección relevante si es posible. Por ejemplo, utiliza :pep:`20#easter-egg` o :pep:`Huevo de Pascua <20#easter-egg>`.
Utiliza :mimetype: para referirse a un Tipo MIME a menos que el valor esté citado en un ejemplo de código.
Utiliza :envvar: para referenciar una variable de entorno. También es posible que debas definir una referencia a la documentación para esa variable de entorno utilizando .. envvar::.
Utiliza :cve: para referenciar un identificador de vulnerabilidad común y exposición (CVE). Por ejemplo, utiliza :cve:`2019-14232`.
Además del marcado incorporado por Sphinx <sphinx:rst-index>, los docs de Django definen algunos unidades de descripción extra:
Configuraciones:
.. setting:: INSTALLED_APPS
Para enlazar a una configuración, utiliza :setting:`INSTALLED_APPS`.
Etiquetas de plantilla:
.. templatetag:: regroup
Para enlazar, utiliza :ttag:`regroup``.
Filtros de plantilla:
.. templatefilter:: linebreaksbr
Para enlazar, utiliza :tfilter:`linebreaksbr`.
Consultas de campo (es decir, Foo.objects.filter(bar__exact=whatever)):
.. fieldlookup:: exact
Para enlazar, utiliza :lookup:`exact`.
Comandos de django-admin:
.. django-admin:: migrate
Para enlazar, utiliza :djadmin:`migrate`.
Opciones de línea de comandos de django-admin:
.. django-admin-option:: --traceback
Para enlazar, utiliza :option:``command_name –traceback` (o omite command_name para las opciones compartidas por todos los comandos como --verbosity).
Enlaces a tickets de Trac (generalmente reservados para notas de lanzamiento de parches):
:ticket:`12345`
La documentación de Django utiliza una directiva personalizada console para documentar ejemplos de línea de comandos que involucran django-admin, manage.py, python, etc.). En la documentación HTML, se renderiza una interfaz de usuario con dos pestañas, con una pestaña que muestra un prompt de comando estilo Unix y otra pestaña que muestra un prompt de Windows.
Ejemplo: puedes reemplazar este fragmento:
use this command:
.. code-block:: console
$ python manage.py shell
con esta una:
use this command:
.. console::
$ python manage.py shell
Nota dos cosas:
Suelen reemplazar las ocurrencias de la directiva .. code-block:: console.
No necesitas cambiar el contenido real del ejemplo de código. Todavía lo escribes suponiendo un entorno Unix-like (es decir, un símbolo de promp '$', componentes de ruta de archivo separados por '/', etc.).
El ejemplo anterior renderizará un bloque de código con dos pestañas. La primera mostrará:
$ python manage.py shell
(.. code-block:: console)
La traducción de los textos es la siguiente:
...\> py manage.py shell
Nuestra política para nuevas características es:
Toda documentación de nuevas características debe escribirse de manera que designe claramente las características que solo están disponibles en la versión de desarrollo de Django. Supongamos que los lectores de la documentación están utilizando la última versión de lanzamiento, no la versión de desarrollo.
Nuestra forma preferida para marcar nuevas características es prefiriendo la documentación de las características con: «.. versionadded:: X.Y», seguido de una línea en blanco obligatoria y una descripción opcional (indentada).
Mejoras generales o cambios en las API que deben destacarse deben utilizar el directive «.. versionchanged:: X.Y» (con el mismo formato que el versionadded mencionado anteriormente.
Estos bloques de versionadded y versionchanged deben ser «autónomos». En otras palabras, ya que solo mantenemos estas anotaciones alrededor durante dos lanzamientos, es agradable poder eliminar la anotación y su contenido sin tener que reflow, reindentar o editar el texto circundante. Por ejemplo, en lugar de poner toda la descripción de una nueva o cambiada característica en un bloque, haz algo como esto:
.. class:: Author(first_name, last_name, middle_name=None)
A person who writes books.
``first_name`` is ...
...
``middle_name`` is ...
.. versionchanged:: A.B
The ``middle_name`` argument was added.
Coloca las notas de anotaciones cambiadas al final de una sección, no al principio.
También, evita referirte a una versión específica de Django fuera de un bloque versionadded o versionchanged. Incluso dentro de un bloque, es a menudo redundante hacerlo así como estos anotaciones se renderizan como «Nueva en Django A.B:» y «Cambió en Django A.B», respectivamente.
Si una función, atributo, etc., se agrega, también está bien utilizar una anotación versionadded como esta:
.. attribute:: Author.middle_name
.. versionadded:: A.B
An author's middle name.
Puedes eliminar la anotación .. versionadded:: A.B sin cambios de indentación cuando sea el momento.
Optimiza la compresión de imágenes donde sea posible. Para archivos PNG, utiliza OptiPNG y AdvanceCOMP’s advpng:
$ cd docs
$ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`
$ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`
Esto se basa en la versión 0.7.5 de OptiPNG. Las versiones anteriores pueden quejarse de que la opción -strip all es pérdida.
Para un ejemplo rápido de cómo todo se ajusta, considera este ejemplo hipotético:
Primero, el documento ref/settings.txt podría tener una disposición general como esta:
========
Settings
========
...
.. _available-settings:
Available settings
==================
...
.. _deprecated-settings:
Deprecated settings
===================
...
A continuación, el documento topics/settings.txt podría contener algo así:
You can access a :ref:`listing of all available settings
<available-settings>`. For a list of deprecated settings see
:ref:`deprecated-settings`.
You can find both in the :doc:`settings reference document
</ref/settings>`.
Utilizamos el elemento de referencia cruzada Sphinx doc cuando queremos enlazar a otro documento como un todo y el elemento ref cuando queremos enlazar a una ubicación arbitraria en un documento.
A continuación, observa cómo se anotan las configuraciones:
.. setting:: ADMINS
ADMINS
======
Default: ``[]`` (Empty list)
A list of all the people who get code error notifications. When
``DEBUG=False`` and a view raises an exception, Django will email these people
with the full exception information. Each member of the list should be a tuple
of (Full name, email address). Example::
[("John", "john@example.com"), ("Mary", "mary@example.com")]
Note that Django will email *all* of these people whenever an error happens.
See :doc:`/howto/error-reporting` for more information.
Este es el texto traducido:
Eso es básicamente cómo todo se ajusta.
Mira Localizar la documentación de Django si quieres ayudar a traducir la documentación a otro idioma.
django-admin¶Sphinx puede generar una página de manuales para el comando django-admin. Esto se configura en docs/conf.py. A diferencia de otros resultados de documentación, esta página de manuales debe incluirse en el repositorio y las versiones de Django como docs/man/django-admin.1. No hay necesidad de actualizar este archivo cuando se actualiza la documentación, ya que se actualiza una vez como parte del proceso de liberación.
Para generar una versión actualizada de la página de manuales, en el directorio docs, ejecuta:
$ make man
La nueva página de manuales estará escrita en docs/_build/man/django-admin.1.
may 31, 2026