Menulis dokumentasi

We place high importance on the consistency and readability of documentation. After all, Django was created in a journalism environment! So we treat our documentation like we treat our code: we aim to improve it as often as possible.

Dokumentasi berubah secara umum datang dalam dua bentuk:

  • Perbaikan 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.

Mendapatkan dokumentasi mentah

Though Django's documentation is intended to be read as HTML at https://docs.djangoproject.com/, we edit it as a collection of text files for maximum flexibility. These files live in the top-level docs/ directory of a Django release.

If you'd like to start contributing to our docs, get the development version of Django from the source code repository (see Memasang versi pengembangan). The development version has the latest-and-greatest documentation, just as it has the latest-and-greatest code. We also backport documentation fixes and improvements, at the discretion of the merger, to the last release branch. That's because it's highly advantageous to have the docs for the last release be up-to-date and correct (see Perbedaan diantara versi).

Mulai dengan Sphinx

Dokumentasi 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.

Untuk membangun dokumentasi lokal, pasang Sphinx:

$ python -m pip install Sphinx
...\> py -m pip install Sphinx

Kemudian dari direktori docs, bangun HTML:

$ make html
...\> make.bat html

Untuk memulai membantu, anda akan ingin membaca reStructuredText reference.

Your locally-built documentation will be accessible at docs/_build/html/index.html and it can be viewed in any web browser, though it will be themed differently than the documentation at docs.djangoproject.com. This is OK! If your changes look good on your local machine, they'll look good on the website.

Bagaimana dokumentasi diatur

Dokumentasi disusun kedalam beberapa kategori:

  • Tutorials membawa pembaca dengan tangan melalui rangkaian langkah-langkah untuk membuat sesuatu.

    Hal terpenting dalam tutorial ini adalah membantu pembaca mendapatkan sesuatu berguna, lebih disukai seawal mungkin, agar memberikan mereka rasa nyaman.

    Explain the nature of the problem we're solving, so that the reader understands what we're trying to achieve. Don't feel that you need to begin with explanations of how things work - what matters is what the reader does, not what you explain. It can be helpful to refer back to what you've done and explain afterward.

  • Topic guides bertujuan untuk menjelaskan konsep atau subjek pada tingkatan yang cukup tinggi.

    Tautkan 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.

    Menyediakan konteks latar belakang membantu pendatang baru menghubungkan topik ke hal-hal yang mereka sudah ketahui.

  • Reference guides contain technical references for APIs. They describe the functioning of Django's internal machinery and instruct in its use.

    Jaga bahan acuan fokus pada subyek. Anggap bahwa pembaca sudah memahami konsep dasar yang dilibatkan tetapi butuh mengetahui atau diingatkan dari bagaimana Django melakukannya.

    Panduan acuan bukanlah tempat untuk penjelasan umum. Jika anda menemukan penjelasan konsep dasar, anda mungkin ingin memindahkan bahan itu ke panduan topik.

  • How-to guides adalah resep yang membawa pembaca melalui langkah-langkah dalam subjek kunci.

    Masalah-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.

    Panduan 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.

Gaya menulis

When using pronouns in reference to a hypothetical person, such as "a user with a session cookie", gender-neutral pronouns (they/their/them) should be used. Instead of:

  • 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
  • dia laki-laki atau dia perempuan... gunakan mereka

Coba untuk menghindari kata-kata yang meminimalkan kesulitan yang terlibat dalam tugas atau operasi, seperti "easily", "simply", "just", "merely", "straightforward", dan seterusnya. Pengalaman orang mungkin tidak cocok dengan harapan anda, dan mereka mungkin menjadi frustasi ketika mereka tidak menemukan langkah seperti "straightforward" atau "simple" seperti yang tersirat.

Istilah umum digunakan

Ini adalah beberapa panduan pada istilah paling umum digunakan sepanjang dokumentasi:

  • Django -- ketika mengacukan ke kerangka kerja, huruf besarkan Django. Huruf kecil hanya dalam kode Python dan dalam logo djangoproject.com.
  • surel -- tanpa tanda penghubung
  • HTTP -- the expected pronunciation is "Aitch Tee Tee Pee" and therefore should be preceded by "an" and not "a".
  • 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").
  • the web, web framework -- tidak huruf besar.
  • website -- gunakan satu kata, tanpa huruf besar.

Istilah khusus-Django

  • 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 untuk berkas-berkas reStructuredText

Panduan ini mengatur bentuk dari dokumentasi dari reST (reStructuredText) kami:

  • Di 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.

  • The main thing to keep in mind as you write and edit docs is that the more semantic markup you can add the better. So:

    Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
    

    Isn't nearly as helpful as:

    Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
    

    Ini karena Sphinx akan membangkitkan kaitan yang tepat untuk yang terakhir, yang sangat membantu pembaca.

    Anda dapat mengawali sasaran dengan ~ (yaitu sebuah tilde) untuk hanya mendapatkan "last bit" dari jalur itu. Jadi :mod:`~django.contrib.auth` akan menampilkan sebuah tautan dengan judul "auth".

  • All Python code blocks should be formatted using the blacken-docs auto-formatter. This will be run by pre-commit if that is configured.

  • Gunakan intersphinx untuk mengacu dokumentasi Python and Sphinx'.

  • Tambah .. code-block:: <lang> pada blok yang persis sehingga mereka akan didapati disoroti. Memilih bergantung pada penorotan otomatis menggunakan :: (dua tanda titik dua). Ini memiliki keuntungan jika kode mengandung beberapa sintaksis tidak sah, iu tidak akan disorot. Menambahkan .. code-block:: python, sebagai contoh, akan memaksa penyorotan daripada sintaksis tidak sah..

  • Untuk meningkatkan kemampuan membaca, gunakan .. admonition:: Descriptive title daripada .. note::. Gunakan kotak-kotak dengan hemat.

  • Use these heading styles:

    ===
    One
    ===
    
    Two
    ===
    
    Three
    -----
    
    Four
    ~~~~
    
    Five
    ^^^^
    
  • Gunakan :rfc: utnuk mengacu RFC dan coba tautkan ke bagian terkait jika mungkin. Sebagai contoh, gunakan :rfc:`2324#section-2.3.2` atau :rfc:`Custom link text <2324#section-2.3.2>`.

  • Use :pep: to reference a Python Enhancement Proposal (PEP) and try to link to the relevant section if possible. For example, use :pep:`20#easter-egg` or :pep:`Easter Egg <20#easter-egg>`.

  • Use :mimetype: to refer to a MIME Type unless the value is quoted for a code example.

  • Use :envvar: to refer to an environment variable. You may also need to define a reference to the documentation for that environment variable using .. envvar::.

Changed in Django 4.2:

All Python code blocks in the Django documentation were reformatted with blacken-docs.

Markah khusus-Django

Selain Sphinx's built-in markup, dokumen Django menentukan beberapa satuan penjelasan tambahan:

  • Settings:

    .. setting:: INSTALLED_APPS
    

    Untuk mengkaitkan ke pengaturan, gunakan :setting:`INSTALLED_APPS`.

  • Template tags:

    .. templatetag:: regroup
    

    Untuk mengkaitkan, gunakan :ttag:`regroup`.

  • Template filters:

    .. templatefilter:: linebreaksbr
    

    Untuk mengkaitkan, gunakan :tfilter:`linebreaksbr`.

  • Field lookups (i.e. Foo.objects.filter(bar__exact=whatever)):

    .. fieldlookup:: exact
    

    Untuk mengkaitkan, gunakan :lookup:`exact`.

  • django-admin commands:

    .. django-admin:: migrate
    

    Untuk mengkaitkan, gunakan :djadmin:`migrate`.

  • django-admin command-line options:

    .. django-admin-option:: --traceback
    

    Untuk menautkan, gunakan :option:`command_name --traceback` (atau hilangkan command_name untuk pilihan yang dibagi oleh semua perintah seperti --verbosity).

  • Links to Trac tickets (typically reserved for patch release notes):

    :ticket:`12345`
    

Django's documentation uses a custom console directive for documenting command-line examples involving django-admin, manage.py, python, etc.). In the HTML documentation, it renders a two-tab UI, with one tab showing a Unix-style command prompt and a second tab showing a Windows prompt.

For example, you can replace this fragment:

use this command:

.. code-block:: console

    $ python manage.py shell

with this one:

use this command:

.. console::

    $ python manage.py shell

Perhatikan dua hal:

  • Anda 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:

$ python manage.py shell

(Tidak ada perubahan dari apa .. code-block:: console akan dibangun).

Yang kedua akan menunjukkan:

...\> py manage.py shell

Mendokumentasikan fitur baru

Kebijakan kami untuk fitur baru adalah:

All documentation of new features should be written in a way that clearly designates the features that are only available in the Django development version. Assume documentation readers are using the latest release, not the development version.

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).

General improvements or other changes to the APIs that should be emphasized should use the ".. versionchanged:: X.Y" directive (with the same format as the versionadded mentioned above.

These versionadded and versionchanged blocks should be "self-contained." In other words, since we only keep these annotations around for two releases, it's nice to be able to remove the annotation and its contents without having to reflow, reindent, or edit the surrounding text. For example, instead of putting the entire description of a new or changed feature in a block, do something like this:

.. 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.

Taruh perubahan catatan penjelasan pada bawah dari bagian, bukan diatas.

Juga, 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.

If a function, attribute, etc. is added, it's also okay to use a versionadded annotation like this:

.. attribute:: Author.middle_name

    .. versionadded:: A.B

    An author's middle name.

Kami dapat memindahkan catatan``.. versionadded:: A.B`` tanpa perubahan lekukan apapun ketika waktu datang.

Mengecilkan gambar

Optimalkan pemampatan gambar dimana memungkinkan. Untuk berkas-berkas PNG, gunakan OptiPNG dan advpng AdvanceCOMP:

$ 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"`

This is based on OptiPNG version 0.7.5. Older versions may complain about the -strip all option being lossy.

Sebuah contoh

Untuk contoh cepat dari bagaimana semua cocok bersama-sama, pertimbangkan contoh hipotesis ini:

  • Pertama, dokumen ref/settings.txt dapat mempunyai tata letak keseluruhan seperti ini:

    ========
    Settings
    ========
    
    ...
    
    .. _available-settings:
    
    Available settings
    ==================
    
    ...
    
    .. _deprecated-settings:
    
    Deprecated settings
    ===================
    
    ...
    
  • Selanjutnya, dokumen topics/settings.txt dapat mengandung sesuatu seperti ini:

    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>`.
    

    We use the Sphinx doc cross-reference element when we want to link to another document as a whole and the ref element when we want to link to an arbitrary location in a document.

  • Selanjutnya, perhatikan bagaimana pengaturan dijelaskan:

    .. 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.
    

    Markah 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.

Pemeriksaan ejaan

Before you commit your docs, it's a good idea to run the spelling checker. You'll need to install sphinxcontrib-spelling first. Then from the docs directory, run make spelling. Wrong words (if any) along with the file and line number where they occur will be saved to _build/spelling/output.txt.

Jika anda menghadapi false-positives (kesalahan keluaran yang sebenarnya benar), lakukan satu dari berikut:

  • Surround inline code or brand/technology names with double grave accents (``).
  • 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).

menterjemahkan dokumentasi

Lihat Localizing the Django documentation jika anda suka membantu menterjemahkan dokumentasi kedalam bahasa lain.

Halaman panduan django-admin

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.