Kami menempatkan sangat penting pada konsistensi dan kesiapan dari dokumentasi. Lagipula, Django dibuat dalam lingkungan jurnalis! Jadi kami memperlakukan dokumentasi kami seperti kami memperlakukan kode kami: kami membidik untuk meningkatkannya sesering mungkin.
\nDokumentasi berubah secara umum datang dalam dua bentuk:
\nPerbaikan umum: pembenaran kesalahan ketik, perbaikan kesalahan dan penjelasan lebih baik melalui penulisan lebih jelas dan lebih contoh.
Fitur baru: dokumentasi dari ditur yang telah ditambahkan ke kerangka kerja sejak terbitan terakhir.
Bagian ini menjelaskan bagaimana penulis dapat mengerjakan perubahan dokumentasi mereka dalam cara paling berguna dan setidaknya lawan kesalahan.
\nMeskipun dokumentasi Django diperuntukkan untuk dibaca sebagai HTML di https://docs.djangoproject.com/, kami menyuntingnya sebagai kumpulan dari berkas-berkas teks untuk fleksibel maksimal. Berkas-berkas ini berada di tingkat-atas pelipat docs/ dari terbitan Django.
Jika anda ingin mulai memperbaiki dokumen kami, dapatkan versi pengembangan dari Django dari gudang kode sumber (lihat Memasang versi pengembangan). Versi pengembangan mempunyai dokumentasi terakhir-dan-terhebat, hanya karena itu memiliki kode terakhir-dan-terhebat. Kami juga backport dokumentasi pembenaran dan perbaikan, pada kebijaksanaan dari pembuat perbaikan, ke cabang terbitan terakhir. Yakni karena itu sangat menguntungkan memiliki dokumen untuk terbitan terakhir menjadi terbaru dan benar (lihat Perbedaan diantara versi).
\nDokumentasi Django menggunakan sistem dokumentasi Sphinx, yang pada gilirannya berdasarkan pada docutils. Ide dasar adalah bahwa dokumentasi teks-tawar berbentuk-ringan dirubah kedalam HTML, PDF, dan bentuk keluaran lainnya.
\nUntuk membangun dokumentasi lokal, pasang Sphinx:
\nLinux / macOS
$ pip install Sphinx\nWindows
...\\> pip install Sphinx\nKemudian dari direktori docs, bangun HTML:
Linux / macOS
$ make html\nWindows
...\\> make.bat html\nUntuk memulai membantu, anda akan ingin membaca reStructuredText reference.
\nDokumentasi bangun-lokal anda akan di temakan berbeda dari dokumentasi pada docs.djangoproject.com. Ini adalah OKE! Jika perubahan anda terlihat baik pada mesin lokal anda, mereka akan mencari hal yang baik pada situs jaringan.
\nDokumentasi disusun kedalam beberapa kategori:
\nTutorials membawa pembaca dengan tangan melalui rangkaian langkah-langkah untuk membuat sesuatu.
\nHal terpenting dalam tutorial ini adalah membantu pembaca mendapatkan sesuatu berguna, lebih disukai seawal mungkin, agar memberikan mereka rasa nyaman.
\nJelaskan sifat dari masalah kami sedang tangani, sehingga pembaca mengerti apa kami sedang coba capai. Jangan merasa bahwa anda butuh memulai dengan penjelasan bagaimana hal-hal bekerja - apa masalahnya adalah apa yang pembaca lakukan, bukan apa anda jelaskan. Itu dapat membantu menunjukkan kembali ke apa anda telah lakukan dan jelaskan kemudian.
\nTopic guides bertujuan untuk menjelaskan konsep atau subjek pada tingkatan yang cukup tinggi.
\nTautkan ke bahan acuan daripada mengulanginya. Gunakan contoh dan jangan enggan menjelaskan hal-hal yang kelihatan sangan dasar ke anda- itu mungkin penjelasan seseorang lain butuhkan.
\nMenyediakan konteks latar belakang membantu pendatang baru menghubungkan topik ke hal-hal yang mereka sudah ketahui.
\nReference guides mengandung acuan teknis untuk API. Mereka menggambarkan fungsi dari perlengkapan dalam Django dan petunjuk dalam penggunaannya.
\nJaga bahan acuan fokus pada subyek. Anggap bahwa pembaca sudah memahami konsep dasar yang dilibatkan tetapi butuh mengetahui atau diingatkan dari bagaimana Django melakukannya.
\nPanduan acuan bukanlah tempat untuk penjelasan umum. Jika anda menemukan penjelasan konsep dasar, anda mungkin ingin memindahkan bahan itu ke panduan topik.
\nHow-to guides adalah resep yang membawa pembaca melalui langkah-langkah dalam subjek kunci.
\nMasalah-masalah apa paling di panduan bagaimana adalah apa yang pengguna ingin untuk dicapai. Bagaimana harus selalu berorientasi hasil daripada fokus pada rincian internal dari bagaimana Django menerapkan apapun yang sedang diobrolkan.
\nPanduan ini lebih maju daripada tutorial dan anggapan beberapa pengetahuan tentang bagaimana Django bekerja. Anggap bahwa pembaca telah mengikuti tutorial dan tidak ragu-ragu untuk menunjuk pembaca kembali ke tutorial sesuai daripada mengulangi bahan yang sama.
\nKetika menggunakan kata ganti di acuan pada hipotesis orang, seperti "pengguna dengan sesi kue", kata ganti netral kelamin (they/their/them) harus digunakan. Sebagai gantinya:
\ndia laki-laki atau dia perempuan... gunakan mereka
dia laki-laki atau dia perempuan... gunakan mereka
dia laki-laki atau dia perempuan... gunakan mereka
dia laki-laki atau dia perempuan... gunakan mereka
dia laki-laki atau dia perempuan... gunakan mereka
Try to avoid using words that minimize the difficulty involved in a task or\noperation, such as "easily", "simply", "just", "merely", "straightforward", and\nso on. People's experience may not match your expectations, and they may become\nfrustrated when they do not find a step as "straightforward" or "simple" as it\nis implied to be.
\nIni adalah beberapa panduan pada istilah paling umum digunakan sepanjang dokumentasi:
\nDjango -- ketika mengacukan ke kerangka kerja, huruf besarkan Django. Huruf kecil hanya dalam kode Python dan dalam logo djangoproject.com.
surel -- tanpa tanda penghubung
MySQL, PostgreSQL, SQLite
SQL -- ketika mengacu pada SQL, pengucapan yang diharapkan seharusnya "Ess Queue Ell" dan bukan "sequel". Dengan demikian dalam frase seperti "Returns an SQL expression", "SQL" harus didahului oleh "an" dan bukan "a".
Python -- ketika mengac ke bahasa, huruf besar kan Python.
realize, customize, initialize, etc. -- menggunakan akhiran Amerika "ize", bukan "ise."
subkelas -- itu adalah kata tunggal tanpa tanda penghubung, kedua sebagai kata kerja ("subkelas model itu") dan sebagai kata benda ("buat sebuah subkelas").
Web, World Wide Web, the Web -- catat Web selalu huruf besar ketika mengacu pada World Wide Web.
website -- gunakan satu kata, tanpa huruf besar.
model -- itu tidak huruf besar.
template -- itu tidak huruf besar.
URLconf -- gunakan tiga huruf besar, tanpa ruang sebelum "conf."
view -- itu tidak huruf besar.
Panduan ini mengatur bentuk dari dokumentasi dari reST (reStructuredText) kami:
\nDi judul bagian, huruf besar hanya kata permulaan dan kata benda yang tepat.
Bungkus dokumentasi pada lebar 80 karakter, meskipun sebuah contoh kode secara signifikan kurang dibaca ketika dipisah terhadap dua baris, atau untukalasan baik lainnya.
Hal utama untuk diingat ketika anda menulis dan menyunting dokumen adalah bahwa lebih markah semantik anda dapat tambah lebih baik. jadi:
\nAdd ``django.contrib.auth`` to your ``INSTALLED_APPS``...\nHampir tidak bermanfaat sebagai
\nAdd :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...\nIni karena Sphinx akan membangkitkan kaitan yang tepat untuk yang terakhir, yang sangat membantu pembaca.
\nAnda dapat awali sasaran dengan sebuah ~ (itu adalah tilde) untuk mendapatkan "bit terakhir" dari jalur. Jadi :mod:`~django.contrib.auth` akan hanya menampilkan sebuah tautan dengan judul "auth".
Gunakan intersphinx untuk mengacu dokumentasi Python and Sphinx'.
Tambah .. code-block:: <lang> pada blok tepat sehingga mereka mendapatkan disorot. Pilih mengandalkan pada penyorotan otomatis hanya menggunakan :: (dua titik dua). Ini mempunyai keuntungan bahwa jika kode mengandung beberapa sintaksis tidak sah, itu tidak akan disorot. Menambahkan .. code-block:: python, sebagai contoh, akan memaksa menyorot meskipun sintaksis tidak sah.
Gunakan gaya kepala ini:
\n===\nOne\n===\n\nTwo\n===\n\nThree\n-----\n\nFour\n~~~~\n\nFive\n^^^^\nUse :rfc: to reference RFC and and try to link to the\nrelevant section if possible. For example, use :rfc:`2324#section-2.3.2`\nor :rfc:`Custom link text <2324#section-2.3.2>`.
Selain Sphinx's built-in markup, dokumen Django menentukan beberapa satuan penjelasan tambahan:
\nPengaturan:
\n.. setting:: INSTALLED_APPS\nUntuk mengkaitkan ke pengaturan, gunakan :setting:`INSTALLED_APPS`.
Cetakan etiket:
\n.. templatetag:: regroup\nUntuk mengkaitkan, gunakan :ttag:`regroup`.
Cetakan penyaring:
\n.. templatefilter:: linebreaksbr\nUntuk mengkaitkan, gunakan :tfilter:`linebreaksbr`.
Pencarian bidang (yaitu Foo.objects.filter(bar__exact=whatever)):
.. fieldlookup:: exact\nUntuk mengkaitkan, gunakan :lookup:`exact`.
Perintah django-admin:
.. django-admin:: migrate\nUntuk mengkaitkan, gunakan :djadmin:`migrate`.
Pilihan baris-perintah django-admin:
.. django-admin-option:: --traceback\nUntuk menautkan, gunakan :option:`command_name --traceback` (atau hilangkan command_name untuk pilihan yang dibagi oleh semua perintah seperti --verbosity).
Tautan ke tiket Trac (khususnya disediakan untuk catatan terbitan tambalan):
\n:ticket:`12345`\nDokumentasi Django menggunakan petunjuk console penyesuaian untuk mendokumentasikan contoh-contoh baris-perintah melibatkan django-admin.py, manage.py, python, dll.). Dalam dokumentasi HTML, itu membangun dua-tab UI, dengan tab pertama menunjukkan prompt perintah gaya-Unix dan tab kedua menunjukkan prompt Windows.
Sebagai contoh, anda dapat mengganti potongan ini:
\nuse this command:\n\n.. code-block:: console\n\n $ python manage.py shell\ndengan satu ini:
\nuse this command:\n\n.. console::\n\n $ python manage.py shell\nPerhatikan dua hal:
\nAnda biasanya akan mengganti kebiasaan dari arahan .. code-block:: console.
Anda tidak butuh merubah isi sebenarnya dari contoh kode. Anda masih menulis itu menganggap lingkungan Unix-y (yaitu. sebuah simbol prompt '$', '/' sebagai jalur sistem berkas pemisah komponen, dll.)
Contoh diatas akan membangun sebuah blok contoh kode dengan dua tab. Pertama akan menunjukkan:
\n$ python manage.py shell\n(Tidak ada perubahan dari apa .. code-block:: console akan dibangun).
Yang kedua akan menunjukkan:
\n...\\> py manage.py shell\nKebijakan kami untuk fitur baru adalah:
\n\n\nSemua dokumentasi dari fitur baru harus ditulis dalam cara yang menamai jelas fitur hanya tersedia di versi pengembangan Django. Anggap dokumetnasi menggunakan terbitan terakhir, bukan versi pengembangan.
\n
Pilihan cara kami untuk menandai fitur baru adalah dengan mendahulukan fitur dokumentasi dengan ".. versionadded:: X.Y", diikuti oleh baris kosong wajib dan pilihan gambaran (bertakuk).
Perbaikan umum, atau perubahan lain pada API yang harus digarisbawahi harus menggunakan petunjuk ".. versionchanged:: X.Y" (dengan bentuk sama sebagai versionadded disebutkan diatas.
Blok versionadded dan versionchanged ini harus "berdikari". Dengan kata lain, sejak kami hanya menjaga keterangan ini sekitar untuk dua terbitan, itu sangat baik dapat memindahkan keterangan dan isinya tanpa harus reflow, memasukkan ulang, atau menyunting teks sekelilingnya. Sebagai contoh, daripada menaruh gambaran keseluruhan dari fitur baru atau berubah dalam blok, lakukan sesuatu seperti ini:
.. class:: Author(first_name, last_name, middle_name=None)\n\n A person who writes books.\n\n ``first_name`` is ...\n\n ...\n\n ``middle_name`` is ...\n\n .. versionchanged:: A.B\n\n The ``middle_name`` argument was added.\nTaruh perubahan catatan penjelasan pada bawah dari bagian, bukan diatas.
\nJuga, hindari menunjukkan pada versi khusus dari Django diluar blok versionadded atau versionchanged. Bahkan didalam sebuah blok, itu sering berulang untuk melakukan seperti pembangun keterangan ini seperti "Baru di Django A.B:" and "Berubah di Django A.B", masing-masing.
Jika sebuah fungsi, atribut, dll. ditambahkan, itu juga tidak masalah menggunakan keterangan versionadded seperti ini:
.. attribute:: Author.middle_name\n\n .. versionadded:: A.B\n\n An author's middle name.\nKami dapat dengan mudah memindahkan keterangan .. versionadded:: A.B tanpa perubahan lekukan ketika waktu datang.
Optimalkan pemampatan gambar dimana memungkinkan. Untuk berkas-berkas PNG, gunakan OptiPNG dan advpng AdvanceCOMP:
$ cd docs\n$ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`\n$ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`\nIni berbasis pada OptiPNG versi 0.7.5. Versi lama mungkin mengeluh tentang pilihan --strip all menjadi lossy.
Untuk contoh cepat dari bagaimana semua cocok bersama-sama, pertimbangkan contoh hipotesis ini:
\nPertama, dokumen ref/settings.txt dapat mempunyai tata letak keseluruhan seperti ini:
========\nSettings\n========\n\n...\n\n.. _available-settings:\n\nAvailable settings\n==================\n\n...\n\n.. _deprecated-settings:\n\nDeprecated settings\n===================\n\n...\nSelanjutnya, dokumen topics/settings.txt dapat mengandung sesuatu seperti ini:
You can access a :ref:`listing of all available settings\n<available-settings>`. For a list of deprecated settings see\n:ref:`deprecated-settings`.\n\nYou can find both in the :doc:`settings reference document\n</ref/settings>`.\nKami menggunakan Sphinx doc unsur penunjukan silang ketika kami ingin menautkan dokumen lain sebagai keseluruhan dan unsur ref ketika kami ingin menautkan tempat berubah-ubah dalam sebuah dokumen.
Selanjutnya, perhatikan bagaimana pengaturan dijelaskan:
\n.. setting:: ADMINS\n\nADMINS\n======\n\nDefault: ``[]`` (Empty list)\n\nA list of all the people who get code error notifications. When\n``DEBUG=False`` and a view raises an exception, Django will email these people\nwith the full exception information. Each member of the list should be a tuple\nof (Full name, email address). Example::\n\n [('John', 'john@example.com'), ('Mary', 'mary@example.com')]\n\nNote that Django will email *all* of these people whenever an error happens.\nSee :doc:`/howto/error-reporting` for more information.\nMarkah ini mengikuti kepala sebagai sasaran "resmi" untuk mengatur ADMINS. Ini berarti tiap waktu Saya berkata tentang ADMINS, Saya dapat menunjukkannya menggunakan :setting:`ADMINS`.
Itu adalah secara dasar bagaimana semuanya cocok bersama-sama.
\nSebelum anda memperbaiki dokumen anda, adalah ide bagus untuk menjalankan pemeriksa ejaan. Anda akan butuh memasang sepasang paket terlebih dahulu:
\nKemudian dari pelipat docs, jalankan make spelling. Kata-kata salah (jika ada) bersama dengan berkas dan nomor baris dimana mereka muncul akan disimpan ke _build/spelling/output.txt.
Jika anda menghadapi false-positives (kesalahan keluaran yang sebenarnya benar), lakukan satu dari berikut:
\nKelilingi kode berjejer atau nama merek/teknologi dengan aksen kuburan (`).
Temukan kesamaan pengenalan pemeriksa ejaan.
Jika, dan hanya jika, anda yakin kata anda gunakan adalah benar -- tambahkan ke docs/spelling_wordlist (silahkan simpan daftar dalam urutan alfabet).
Lihat Localizing the Django documentation jika anda suka membantu menterjemahkan dokumentasi kedalam bahasa lain.
\ndjango-adminLink to this heading#Sphinx dapat membangkitkan sebuah halaman panduan untuk perintah django-admin. Ini dikonfigurasikan dalam docs/conf.py. Tidak seperti keluaran dokumentasi lainnya, halaman bantuan ini harus disertakan dalam gudang Django dan terbitan sebagai docs/man/django-admin.1. Tidak perlu memperbaharui berkas ini ketika memperbaharui dokumentasi, seperti dia diperbaharui sekali sebagai bagian dari pengolahan terbitan.
Untuk membangkitkan versi terperbaharui dari halaman bantuan, jalankan make man di pelipat docs. Halaman bantuan baru akan ditulis dalam docs/_build/man/django-admin.1.