We place high importance on the consistency and readability of documentation.\nAfter all, Django was created in a journalism environment! So we treat our\ndocumentation like we treat our code: we aim to improve it as often as\npossible.
\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.
\nThough Django's documentation is intended to be read as HTML at\nhttps://docs.djangoproject.com/, we edit it as a collection of plain text files\nwritten in the reStructuredText markup language for maximum flexibility.
\nWe work from the development version of the repository because it has the\nlatest-and-greatest documentation, just as it has the latest-and-greatest code.
\nWe also backport documentation fixes and improvements, at the discretion of the\nmerger, to the last release branch. This is because it's advantageous to\nhave the docs for the last release be up-to-date and correct (see\nPerbedaan 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.
\nSphinx menyertakan perintah sphinx-build untuk merubah reStructuredText kedalam bentuk lain, misalnya HTML dan PDF. Perintah ini dapat dikonfigurasi, tetapi dokumentasi Django menyertakan Makefile yang menyediakan perintah pendek make html.
Dokumentasi 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.
\nExplain the nature of the problem we're solving, so that the reader\nunderstands what we're trying to achieve. Don't feel that you need to begin\nwith explanations of how things work - what matters is what the reader does,\nnot what you explain. It can be helpful to refer back to what you've done and\nexplain afterward.
\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 contain technical references for APIs.\nThey describe the functioning of Django's internal machinery and instruct in\nits use.
\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.
\nIf you'd like to start contributing to our docs, get the development version of\nDjango from the source code repository (see\nMemasang versi pengembangan):
\nLinux / macOS
$ git clone https://github.com/django/django.git\nWindows
...\\> git clone https://github.com/django/django.git\nIf you're planning to submit these changes, you might find it useful to make a\nfork of the Django repository and clone this fork instead.
\nCreate and activate a virtual environment, then install the dependencies:
\n$ python -m venv .venv\n$ source .venv/bin/activate\n$ python -m pip install -r docs/requirements.txt\nWe can build HTML output from the docs directory:
Linux / macOS
$ cd docs\n$ make html\nWindows
...\\> cd docs\n...\\> make.bat html\nDokumentasi bangun-lokal anda akan dapat diakses di _build/html/index.html dan dapat ditampilkan di peramban manapun, meski akan bertema berbeda dari pada dokumentasi di docs.djangoproject.com. Ini OKE! Jika perubahan anda terlihat bagus pada mesin lokal anda, mereka akan terlihat bagus di situs jaringan.
sphinx-autobuild can be used to automatically rebuild the documentation\nand reload the documentation page in the browser whenever a file changes. To\nenable auto-reloading:
\nInstall the package:
\nLinux / macOS
$ python -m pip install sphinx-autobuild\nWindows
...\\> py -m pip install sphinx-autobuild\nFrom the docs directory, run one of the following commands:
On Linux and macOS:
\n$ SPHINXBUILD=sphinx-autobuild SPHINXOPTS="--open-browser --delay 0" make html\nOn Windows (Command Prompt):
\n...\\> set SPHINXBUILD=sphinx-autobuild\n...\\> set SPHINXOPTS=--open-browser --delay 0\n...\\> make html\nOn Windows (PowerShell):
\nPS> $env:SPHINXBUILD="sphinx-autobuild"\nPS> $env:SPHINXOPTS="--open-browser --delay 0"\nPS> make html\nAlternatively, sphinx-autobuild can be invoked directly:
Linux / macOS
$ sphinx-autobuild . _build/html --open-browser --delay 0\nWindows
...\\> sphinx-autobuild . _build\\html --open-browser --delay 0\nThe auto-reloader can be stopped with Ctrl+C.
The source files are .txt files located in the docs/ directory.
These files are written in the reStructuredText markup language. To learn the\nmarkup, see the reStructuredText reference.
\nTo edit this page, for example, we would edit the file\ndocs/internals/contributing/writing-documentation.txt and rebuild the\nHTML with make html.
Several checks help maintain Django's documentation quality, including\nspelling,\ncode block formatting, and\ndocumentation style.
\nThese checks are run automatically in CI and must pass before documentation\nchanges can be merged. They can also be run locally with a single command:
\nLinux / macOS
$ make check\nWindows
...\\> make.bat check\nThis command runs all current checks and will include any new checks added in\nthe future.
\nBefore you commit your docs, it's a good idea to run the spelling checker.\nYou'll need to install sphinxcontrib-spelling first. The spell checker\nalso requires a system-level spell checking backend such as Aspell. Then from the docs directory, run:
Linux / macOS
$ make spelling\nWindows
...\\> make.bat spelling\nWrong words (if any) along with the file and line number where they occur will\nbe saved to _build/spelling/output.txt.
Jika anda menghadapi false-positives (kesalahan keluaran yang sebenarnya benar), lakukan satu dari berikut:
\nSurround inline code or brand/technology names with double grave accents\n(``)
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).
All Python code blocks should be formatted using the blacken-docs\nauto-formatter. This is automatically run by the pre-commit hook if configured.
\nThe check can also be run manually: provided that blacken-docs is\ninstalled, run the following command from the docs directory:
Linux / macOS
$ make black\nWindows
...\\> make.bat black\nThe formatter will report any issues by printing them to the terminal and will\nreformat code blocks where possible.
\nDjango's documentation is checked for reStructuredText style and formal issues\nusing sphinx-lint. This helps catch problems like stray tabs, trailing\nwhitespace, excessive line length, and similar formatting problems.
\nOnce sphinx-lint is installed, the check can be run with the following\ncommand from the docs directory:
Linux / macOS
$ make lint\nWindows
...\\> make.bat lint\nThe command prints any violations to the terminal in the form\npath:line: message. If problems are encountered:
Read the message and fix the indicated issue (for example, remove trailing\nwhitespace, adjust backticks, or replace tabs with spaces).
For long lines consider wrapping text onto new lines or breaking long inline\nlinks into named references. The custom line length check should already skip\ncommon false positives such as headings, tables and long links.
Links in documentation can become broken or changed such that they are no\nlonger the canonical link. Sphinx provides a builder that can check whether the\nlinks in the documentation are working. From the docs directory, run:
Linux / macOS
$ make linkcheck\nWindows
...\\> make.bat linkcheck\nOutput is printed to the terminal, but can also be found in\n_build/linkcheck/output.txt and _build/linkcheck/output.json.
Entries that have a status of "working" are fine, those that are "unchecked" or\n"ignored" have been skipped because they either cannot be checked or have\nmatched ignore rules in the configuration.
\nMasukan yang mempunyai status "broken" butuh diperbaiki. Mereka yang memiliki status "redirected" butuh diperbaharui ke titik tempat resmi, sisalnya skema telah berubah http:// → https://.Dalam kasus tertentu, kami tidak ingin memperbaharui tautan "redirected" link, misalnya menulis kembali menjadi selalu menunjuk ke terkahir atau versi stabil dari dokumentasi, misalnya /en/stable/ → /en/3.2/.
When using pronouns in reference to a hypothetical person, such as "a user with\na session cookie", gender-neutral pronouns (they/their/them) should be used.\nInstead of:
\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
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.
\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
HTTP -- the expected pronunciation is "Aitch Tee Tee Pee" and therefore\nshould 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.
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.
The main thing to keep in mind as you write and edit docs is that the\nmore semantic markup you can add the better. So:
\nAdd ``django.contrib.auth`` to your ``INSTALLED_APPS``...\nIsn't nearly as helpful as:
\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 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".
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:
\n===\nOne\n===\n\nTwo\n===\n\nThree\n-----\n\nFour\n~~~~\n\nFive\n^^^^\nUse :rfc: to reference a Request for Comments (RFC) and\ntry to link to the relevant section if possible. For example, use\n:rfc:`2324#section-2.3.2` or\n:rfc:`Custom link text <2324#section-2.3.2>`.
Use :pep: to reference a Python Enhancement Proposal (PEP)\nand try to link to the relevant section if possible. For example, use\n:pep:`20#easter-egg` or :pep:`Easter Egg <20#easter-egg>`.
Use :mimetype: to refer to a MIME Type unless the value\nis quoted for a code example.
Use :envvar: to refer to an environment variable. You may\nalso need to define a reference to the documentation for that environment\nvariable using .. envvar::.
Use :cve: to reference a Common Vulnerabilities and\nExposures (CVE) identifier. For example, use :cve:`2019-14232`.
When documenting Python objects (classes, methods, attributes, etc.) using\nSphinx directives such as .. class::, .. method::, and\n.. attribute::, all content must be properly indented to ensure correct\nrendering and to support features like automatic table of contents\ngeneration.
Follow these rules:
\nThe directive itself remains flush with the left margin (no indentation).
All descriptive text under the directive must be indented by 4 spaces.
Multi-line descriptions must keep the same indentation level.
Nested directives (for example, methods inside a class) require an\nadditional 4 spaces of indentation to maintain hierarchy.
Field lists (such as :param:, :returns:, etc.) must align with the\ndirective's content level.
Example:
\n.. class:: MyClass\n\n A brief description of the class.\n\n .. method:: my_method(arg1, arg2)\n\n Method description.\n\n :param arg1: Description of the first parameter\n :param arg2: Description of the second parameter\n\n .. attribute:: my_attribute\n\n Attribute description.\nSelain Sphinx's built-in markup, dokumen Django menentukan beberapa satuan penjelasan tambahan:
\nSettings:
\n.. setting:: INSTALLED_APPS\nUntuk mengkaitkan ke pengaturan, gunakan :setting:`INSTALLED_APPS`.
Template tags:
\n.. templatetag:: regroup\nUntuk mengkaitkan, gunakan :ttag:`regroup`.
Template filters:
\n.. templatefilter:: linebreaksbr\nUntuk mengkaitkan, gunakan :tfilter:`linebreaksbr`.
Field lookups (i.e. Foo.objects.filter(bar__exact=whatever)):
.. fieldlookup:: exact\nUntuk mengkaitkan, gunakan :lookup:`exact`.
django-admin commands:
.. django-admin:: migrate\nUntuk mengkaitkan, gunakan :djadmin:`migrate`.
django-admin command-line options:
.. django-admin-option:: --traceback\nUntuk 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):
\n:ticket:`12345`\nDjango's documentation uses a custom console directive for documenting\ncommand-line examples involving django-admin, manage.py, python,\netc. In the HTML documentation, it renders a two-tab UI, with one tab showing\na Unix-style command prompt and a second tab showing a Windows prompt.
For example, you can replace this fragment:
\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\nAll documentation of new features should be written in a way that\nclearly designates the features that are only available in the Django\ndevelopment version. Assume documentation readers are using the latest\nrelease, not the development version.
\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).
General improvements or other changes to the APIs that should be emphasized\nshould use the ".. versionchanged:: X.Y" directive (with the same format\nas the versionadded mentioned above).
These versionadded and versionchanged blocks should be\n"self-contained." In other words, since we only keep these annotations around\nfor two releases, it's nice to be able to remove the annotation and its\ncontents without having to reflow, reindent, or edit the surrounding text. For\nexample, instead of putting the entire description of a new or changed feature\nin a block, do something like this:
.. 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.
If a function, attribute, etc. is added, it's also okay to use a\nversionadded annotation like this:
.. attribute:: Author.middle_name\n\n .. versionadded:: A.B\n\n An author's middle name.\nKami dapat memindahkan catatan``.. versionadded:: A.B`` tanpa perubahan lekukan apapun ketika waktu datang.
\nOptimalkan pemampatan gambar dimana memungkinkan. Untuk berkas-berkas PNG, gunakan OptiPNG dan advpng AdvanceCOMP:
Linux / macOS
$ 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"`\nWindows
...\\> 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"`\nThis is based on OptiPNG version 0.7.5. Older versions may complain about the\n-strip all option being 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>`.\nWe use the Sphinx doc cross-reference element when we want to\nlink to another document as a whole and the ref element when\nwe want to link to an arbitrary location in a document.
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...\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.
\nLihat 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.
To generate an updated version of the man page, in the docs directory, run:
Linux / macOS
$ make man\nWindows
...\\> make.bat man\nThe new man page will be written in docs/_build/man/django-admin.1.