Aplikasi admindocs
Django menarik dokumentasi dari docstring dari model, tampilan etiket cetakan, dan penyaring cetakan untuk aplikasi apapun di INSTALLED_APPS
dan membuat dokumentasi itu tersedia dari Django admin
.
Untuk mengaktifkan admindocs
, anda akan butuh melakukan berikut:
django.contrib.admindocs
ke INSTALLED_APPS
anda.path('admin/doc/', include('django.contrib.admindocs.urls'))
ke urlpatterns
anda. Pastikan itu disertakan sebelum masukan 'admin/'
, sehingga permintaan ke /admin/doc/
tidak ditangani oleh masukan terakhir.django.contrib.admindocs.middleware.XViewMiddleware
untuk dipasang.Sekali langkah-langkah tersebut lengkap, anda dapat mulai menjelajah dokumentasi dengan pergi ke antarmuka admin anda dan mengklik tautan "Documentation" di atas kanan halaman.
Markah khusus beikur dapat digunakan di docstring anda untuk dengan mudah membuat hyperlink ke komponen lain:
Komponen Django | Peran reStructuredText |
---|---|
Model | :model:`app_label.ModelName` |
View | :view:`app_label.view_name` |
Tag templat | :tag:`tagname` |
Filter templat | :filter:`filtername` |
Templat | :template:`path/to/template.html` |
Bagian model dari halaman admindocs
menggambarkan setiap model dalam sistem bersama dengan semua bidang, sifat, dan metode tersedia pada itu. Hubungan ke model lainnya muncul sebagai hyperlink. Gambaran-gambaran ditarik dari atribut help_text
pada bidang atau dari docstring pada metode model.
Sebuah model dengan dokumentasi berguna mungkin terlihat seperti ini:
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."""
...
Setiap URL di situs anda mempunyai masukan terpisah di halaman admindocs
, dan mengklik pada URL yang diberikan akan menunjukkan anda tampilan berhubungan. Hal-hal membantu anda dapat dokumentasikan di docstring fungsi tampilan anda termasuk:
Sebagai contoh:
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)
Bagian admindocs
etiket and penyaring menggambarkan semua etiket dan penyaring yang datang dengan Django (faktanya, dokumentasi built-in tag reference dan built-in filter reference datang langsung dari halaman-halaman tersebut). Etiket atau penyaring apapun yang anda buat atau ditambahkan oleh aplikasi pihak-ketiga akan tampil di bagian-bgian ini juga.
Selagi admindocs
tidak menyertakan tempat untuk cetakan dokumen oleh mereka sendiri, jika anda menggunakan sintaksis :template:`path/to/template.html`
di sebuah docstring halaman hasil akan memeriksa jalur dari cetakan itu dengan template loaders Django. Ini dapat menjadi cara mudah memeriksa jika cetakan ditentukan ada dan untuk menunjukkan dimana pada sistem berkas cetakan itu disimpan.
Satu bookmarklet tersedia dari halaman admindocs
:
Menggunakan bookmark ini mewajibkan bahwa XViewMiddleware
dipasang dan bahwa anda masuk kedalam Django admin
sebagai sebuah User
dengan is_staff
disetel menjadi True
.
Mei 07, 2024