La documentación generadora del administrador Django

La traducción es:

Resumen

Para activar la ~django.contrib.admindocs, necesitarás hacer lo siguiente:

  • Agrega django.contrib.admindocs a tus INSTALLED_APPS.

  • Añade path(“admin/doc/”, include(“django.contrib.admindocs.urls”)) a tus urlpatterns. Asegúrate de que esté incluido antes de la entrada “admin/”, para que las solicitudes a /admin/doc/ no se manejen por la entrada correspondiente.

  • Instala el paquete docutils 0.19+.

  • Opcional: Para utilizar los marcadores de libro de direcciones admindocs, debe instalarse django.contrib.admindocs.middleware.XViewMiddleware.

Una vez completados estos pasos, puedes empezar a navegar por la documentación accediendo a tu interfaz administrativa y haciendo clic en el enlace «Documentación» en la parte superior derecha de la página.

Ayudas de documentación

Se puede utilizar el siguiente marcado especial en tus docstrings para crear fácilmente enlaces hipertextuales a otros componentes:

Componente Django

Roles reStructuredText

Modelos

:model:`app_label.ModelName`

Vistas

:view:`app_label.view_name`

Etiquetas de plantilla

tagname

Filtros de plantilla

filtername

Plantillas

path/to/template.html

Cada uno de estos admite un texto de enlace personalizado con el formato :role:`texto de enlace <enlace>`. Por ejemplo, :tag:`bloque <bloque_built-in>`.

Se agregó soporte para texto personalizado de enlaces.

Referencia del modelo

La sección de modelos de la página admindocs describe cada modelo al que el usuario tiene acceso, junto con todos los campos, propiedades y métodos disponibles en él. Las relaciones con otros modelos aparecen como enlaces hipertexto. Las descripciones se extraen de las atributos help_text de los campos o de las cadenas de documentación de los métodos del modelo.

Un modelo con documentación útil podría verse así:

class BlogEntry(models.Model):
    """
    Stores a single blog entry, related to :model:`blog.Blog` and
    :model:`auth.User`.
    """

    slug = models.SlugField(help_text="A short label, generally used in URLs.")
    author = models.ForeignKey(
        User,
        models.SET_NULL,
        blank=True,
        null=True,
    )
    blog = models.ForeignKey(Blog, models.CASCADE)
    ...

    def publish(self):
        """Makes the blog entry live on the site."""
        ...

El acceso se restringió para permitir solo a los usuarios con permisos de modelo, vista o cambio.

Referencia de vista

Cada URL de tu sitio tiene una entrada separada en la página admindocs, y hacer clic en un URL dado te mostrará el correspondiente vista.

  • Una breve descripción de lo que hace la vista.

  • El contexto, o una lista de variables disponibles en la plantilla del vista.

  • El nombre del template o plantillas utilizadas para esa vista.

Por ejemplo:

from django.shortcuts import render

from myapp.models import MyModel


def my_view(request, slug):
    """
    Display an individual :model:`myapp.MyModel`.

    **Context**

    ``mymodel``
        An instance of :model:`myapp.MyModel`.

    **Template:**

    :template:`myapp/my_template.html`
    """
    context = {"mymodel": MyModel.objects.get(slug=slug)}
    return render(request, "myapp/my_template.html", context)

Referencia a las etiquetas y filtros de plantilla

Los etiquetas y filtros secciones admindocs describen todas las etiquetas y filtros que vienen con Django (de hecho, la documentación de referencia de etiquetas incorporadas <ref-templates-builtins-tags> y la documentación de referencia de filtros incorporados <ref-templates-builtins-filters> provienen directamente de esas páginas). Cualquier etiqueta o filtro que crees o se agregue mediante una aplicación de terceros aparecerá en estas secciones también.

Referencia de plantilla

Mientras admindocs no incluye un lugar para documentar plantillas por sí solas, si utilizas la sintaxis :template:`path/to/template.html` en una docstring, la página resultante verificará el camino de esa plantilla con los cargadores de plantillas de Django. Esto puede ser una forma útil de comprobar si existe la plantilla especificada y mostrar dónde en el sistema de archivos se almacena esa plantilla.

Incluidos Bookmarklets

Un bookmarklet está disponible desde la página admindocs:

Documentación para esta página

Saltas desde cualquier página a la documentación del view que genera esa página.

Para utilizar este bookmarklet es necesario que esté instalado el XViewMiddleware y que estés conectado al Django admin como un User con is_staff establecido en True.

« previous | up | next »