---
title: "Scríobh cáipéis"
version: 6.0
locale: ga
source: https://docs.djangoproject.com/ga/6.0/internals/contributing/writing-documentation/
canonical: https://djangodocs.dev/ga/6.0/internals/contributing/writing-documentation/
---
# Scríobh cáipéis

Cuirimid an-tábhacht ar chomhsheasmhacht agus ar inléiteacht na ndoiciméad. Tar éis an tsaoil, cruthaíodh Django i dtimpeallacht iriseoireachta! Mar sin caithimid lenár ndoiciméadú mar a chaithimid lenár gcód: tá sé mar aidhm againn é a fheabhsú chomh minic agus is féidir.

De ghnáth is dhá fhoirm a bhíonn athruithe doiciméadaithe:

- Feabhsuithe ginearálta: ceartúcháin tíopála, earráidí a cheartú agus míniúcháin níos fearr trí scríobh níos soiléire agus níos mó samplaí.
- Gnéithe nua: doiciméadú gnéithe a cuireadh leis an gcreat ón scaoileadh deireanach.

Mínítear sa chuid seo conas is féidir le scríbhneoirí athruithe a dhéanamh ar a ndoiciméadú ar na bealaí is úsáidí agus is lú seans go mbeidh earráidí ann.

## An próiseas doiciméadaithe Django

Cé go bhfuil sé beartaithe doiciméadú Django a léamh mar HTML ag <https://docs.djangoproject.com/>, déanaimid é a chur in eagar mar bhailiúchán de chomhaid téacs simplí atá scríofa sa teanga marcála RestructuredText chun an tsolúbthacht is mó a fháil.

Oibrímid ó leagan forbartha an stór toisc go bhfuil an doiciméadú is déanaí agus is mó aige, díreach mar atá an cód is déanaí agus is mó aige.

Déanaimid socruithe agus feabhsuithe doiciméadaithe ar ais freisin, de réir rogha an chumaisc, go dtí an bhrainse scaoilte deireanach. Tá sé seo toisc go bhfuil sé buntáisteach go mbeadh na doiciméid don eisiúint deireanach cothrom le dáta agus ceart (féach: ref: difríochtaí idir doc-versions).

Úsáideann cáipéisíocht Django córas doiciméadaithe [Sphinx](https://www.sphinx-doc.org/), atá bunaithe ar [docutils](https://docutils.sourceforge.io/) ina dhiaidh sin. Is é an smaoineamh bunúsach ná go ndéantar doiciméadú téacs simplí formáidithe go héadrom a athrú go HTML, PDF, agus aon fhormáid aschuir eile.

Cuimsíonn Sphinx ordú `sphinx-build` chun RestructuredText a iompú i bhformáidí eile, m.sh., HTML agus PDF. Tá an t-ordú seo inchumraithe, ach cuimsíonn cáipéisíocht Django `Makefile` a sholáthraíonn ordú `make html` níos giorra.

## Conas a eagraítear na doiciméid

Tá an doiciméadú eagraithe i roinnt catagóirí:

- [Tutorials](/ga/6.0/intro/) take the reader by the hand through a series
  of steps to create something.

  Is é an rud tábhachtach i rang teagaisc cabhrú leis an léitheoir rud éigin úsáideach a bhaint amach, b'fhearr chomh luath agus is féidir, d'fhonn muinín a thabhairt dóibh.

  Mínigh nádúr na fadhbanna atá á réiteach againn, ionas go dtuigeann an léitheoir cad atá againn ag iarraidh a bhaint amach. Ná mhothaigh gur gá duit tosú le mínithe ar an gcaoi a n-oibríonn rudaí - is é an rud is tábhachtaí ná cad a dhéanann an léitheoir, ní an méid a mhíníonn tú D'fhéadfadh sé a bheith cabhrach tagairt a dhéanamh ar ais don méid a rinne tú agus míniú ina dhiaidh sin.
- [Topic guides](/ga/6.0/topics/) aim to explain a concept or subject at a
  fairly high level.

  Nasc le hábhar tagartha seachas é a athdhéanamh. Úsáid samplaí agus ná bíodh drogall ort rudaí atá an-bhunúsach duit a mhíniú - b'fhéidir gurb é an míniú a theastaíonn ó dhuine eile.

  Trí chomhthéacs cúlra a sholáthar cabhraíonn sé le núíosach an topaic a nascadh le rudaí atá ar eolas acu cheana féin.
- [Reference guides](/ga/6.0/ref/) contain technical references for APIs.
  They describe the functioning of Django's internal machinery and instruct in
  its use.

  Coinnigh ábhar tagartha dírithe go docht ar an ábhar. Glac leis go dtuigeann an léitheoir cheana féin na bunchoincheapa atá i gceist ach go gcaithfidh sé fios a bheith aige nó a mheabhrú conas a dhéanann Django é.

  Ní hé treoracha tagartha an áit le haghaidh míniú ginearálta. Má fhaigheann tú tú féin ag míniú bunchoincheapa, b'fhéidir gur mhaith leat an t-ábhar sin a aistriú chuig treoir ábhair.
- [How-to guides](/ga/6.0/howto/) are recipes that take the reader through
  steps in key subjects.

  Is é an rud is tábhachtaí i dtreoir conas is féidir leis an úsáideoir a bhaint amach. Ba chóir go mbeadh conas-le-dírithe i gcónaí ar thorthaí seachas a bheith dírithe ar shonraí inmheánacha faoin gcaoi a gcuireann Django i bhfeidhm cibé rud atá á phlé.

  Tá na treoracha seo níos airde ná ranganna teagaisc agus glacann siad roinnt eolais faoi conas a oibríonn Django. Glac leis gur lean an léitheoir na ranganna teagaisc agus ná bíodh aon leisce ort an léitheoir a tharchur ar ais chuig an rang teagaisc cuí seachas an t-ábhar céanna a athdhéanamh.

## Conas tosú ag cur cáipéisíocht

### Clóin stór Django chuig do mheaisín áitiúil

Más mian leat tosú ag cur lenár ndoiciméad, faigh an leagan forbartha de Django ón stór cód foinse (féach: ref: installing-development-version):

```console
$ git clone https://github.com/django/django.git
```

*Windows*

```doscon
...\> git clone https://github.com/django/django.git
```

Má tá sé ar intinn agat na hathruithe seo a chur isteach, b'fhéidir go mbeadh sé úsáideach duit forc a dhéanamh de stór Django agus an forc seo a chlónú ina ionad sin.

### Cuir timpeallacht fhíorúil ar bun agus spleáchais a shuiteáil

Cruthaigh agus gníomhachtaigh timpeallacht fhíorúil, ansin suiteáil na spleáchais:

```shell
$ python -m venv .venv
$ source .venv/bin/activate
$ python -m pip install -r docs/requirements.txt
```

### Tóg an doiciméadú go háiti

Is féidir linn aschur HTML a thógáil ón eolaire docs\`:

```console
$ cd docs
$ make html
```

*Windows*

```doscon
...\> cd docs
...\> make.bat html
```

Beidh do dhoiciméadú tógtha go háitiúil inrochtana ag `_build/html/index.html` agus is féidir é a fheiceáil in aon bhrabhsálaí gréasáin, cé go mbeidh téama difriúil air ná an doiciméadú ag [docs.djangoproject.com](#docs-djangoproject-com). \< <https://docs.djangoproject.com/>\> Tá sé seo ceart go leor! Má tá cuma mhaith ar d'athruithe ar do mheaisín áitiúil, beidh cuma mhaith orthu ar an suíomh Gréasáin.

### Eagarthóireachtaí a dhéanamh ar an doiciméadacht

Is iad na comhaid foinse comhaid `.txt` atá lonnaithe san eolaire `docs/`.

Tá na comhaid seo scríofa sa teanga marcála RestructuredText. \<sphinx:rst-index\>Chun an marcáil a fhoghlaim, féach an tagairt: ref: RestructuredText .

Chun an leathanach seo a chur in eagar, mar shampla, déanfaimis an comhad:source: docs/internals/contributing/writing-documentation.txt a chur in eagar agus an HTML a atógáil le `make html`.

### Documentation quality checks

Several checks help maintain Django's documentation quality, including
[spelling](#documentation-spelling-check),
[code block formatting](#documentation-code-block-format-check), and
[documentation style](#documentation-lint-check).

These checks are run automatically in CI and must pass before documentation
changes can be merged. They can also be run locally with a single command:

```console
$ make check
```

*Windows*

```doscon
...\> make.bat check
```

This command runs all current checks and will include any new checks added in
the future.

#### Seiceáil litrithe

Before you commit your docs, it's a good idea to run the spelling checker.
You'll need to install [sphinxcontrib-spelling](https://pypi.org/project/sphinxcontrib-spelling/) first. Then from the
`docs` directory, run:

```console
$ make spelling
```

*Windows*

```doscon
...\> make.bat spelling
```

Wrong words (if any) along with the file and line number where they occur will
be saved to `_build/spelling/output.txt`.

Má thagann tú ar dhearfacha bréagacha (aschur earráide atá ceart i ndáiríre), déan ceann de na nithe seo a leanas:

- Surround inline code or brand/technology names with double grave accents
  (\`\`)
- Faigh comhchiallaigh a aithníonn an seiceálaí litrithe.
- Má tá tú cinnte go bhfuil an focal atá á úsáid agat ceart - cuir é le docs/spelling\_wordlist\` (coinnigh an liosta in ord aibítre le do thoil).

#### Code block format check

All Python code blocks should be formatted using the [blacken-docs](https://pypi.org/project/blacken-docs/)
auto-formatter. This is automatically run by the [pre-commit hook](/ga/6.0/internals/contributing/writing-code/coding-style/#coding-style-pre-commit) if configured.

The check can also be run manually: provided that `blacken-docs` is
installed, run the following command from the `docs` directory:

```console
$ make black
```

*Windows*

```doscon
...\> make.bat black
```

The formatter will report any issues by printing them to the terminal and will
reformat code blocks where possible.

#### Documentation lint check

Django's documentation is checked for reStructuredText style and formal issues
using [sphinx-lint](https://pypi.org/project/sphinx-lint/). This helps catch problems like stray tabs, trailing
whitespace, excessive line length, and similar formatting problems.

Once `sphinx-lint` is installed, the check can be run with the following
command from the `docs` directory:

```console
$ make lint
```

*Windows*

```doscon
...\> make.bat lint
```

The command prints any violations to the terminal in the form
`path:line: message`. If problems are encountered:

- Read the message and fix the indicated issue (for example, remove trailing
  whitespace, adjust backticks, or replace tabs with spaces).
- For long lines consider wrapping text onto new lines or breaking long inline
  links into named references. The custom line length check should already skip
  common false positives such as headings, tables and long links.

### Seiceáil nasc

Links in documentation can become broken or changed such that they are no
longer the canonical link. Sphinx provides a builder that can check whether the
links in the documentation are working. From the `docs` directory, run:

```console
$ make linkcheck
```

*Windows*

```doscon
...\> make.bat linkcheck
```

Output is printed to the terminal, but can also be found in
`_build/linkcheck/output.txt` and `_build/linkcheck/output.json`.

> **Warning**
>
> The execution of the command requires an internet connection and takes
> several minutes to complete, because the command tests all the links
> that are found in the documentation.

Tá iontrálacha a bhfuil stádas “ag obair” acu go breá, scipeánadh iad siúd nach bhfuil “neamh-sheiceáil” nó “neamhaird orthu” toisc nach féidir iad a sheiceáil nó gur mheaitseáil siad rialacha neamhaird sa chumraíocht.

Ní mór iontrálacha a bhfuil stádas “briste” acu a shocrú. B'fhéidir go gcaithfear iad siúd a bhfuil stádas “atreoraithe” acu a nuashonrú chun an suíomh canónach a chur in iúl, m.sh. tá athrú tagtha ar an scéim `http: //` → `https: //`. I gcásanna áirithe, níl muid ag iarraidh nasc “atreoraithe” a nuashonrú, m.sh. athscríobh chun an leagan is déanaí nó cobhsaí den doiciméad a chur in iúl i gcónaí, m.sh. /en/stable/\` → `/en/3.2/`.

## Stíl scríobh

Nuair a úsáidtear forainmneacha i dtagairt do dhuine hipitéiseach, mar shampla “úsáideoir le fianán seisiúin”, ba cheart ainmneacha neodrach ó inscne (siú/iad féin) a úsáid. In ionad:

- úsáideann sé nó sí... iad.
- é nó í... bain úsáid as iad.
- a chuid nó í... bain úsáid as a gcuid.
- a chuid féin nó a... bain úsáid as a gcuid féin.
- é féin nó í féin... bain úsáid as iad féin.

Déan iarracht focail a úsáid a sheachaint a íoslaghdaíonn an deacracht a bhaineann le tasc nó oibríocht, mar shampla “go héasca”, “go simplí”, “díreach”, “díreach”, “simplí”, agus mar sin de. B'fhéidir nach n-oireann taithí daoine le d'ionchais, agus d'fhéadfadh go mbeadh frustrachas orthu nuair nach bhfaigheann siad céim chomh “simplí” nó “simplí” agus a thugtar le tuiscint a bheith.

## Téarmaí a úsáidtear go co

Seo roinnt treoirlínte stíle ar théarmaí a úsáidtear go coitianta ar fud an doiciméid:

- **Django** \- agus tú ag tagairt don chreat, caipitligh Django. Níl sé le litreacha beaga ach i gcód Python agus i lógó djangoproject.com.
- **ríomhphost** \- gan aon bhreith.
- **HTTP** \- is é “Aitch Tee Tee Pee” an fuaimniú a bhfuil súil leis agus dá bhrí sin ba cheart “an” agus ní “a” roimh ré.
- **MySQL**, **PostgreSQL**, **SQLite**
- **SQL** \- agus tú ag tagairt do SQL, ba chóir go mbeadh “Ess Queue Ell” an fuaimniú ag súil leis agus ní “seicheamh”. Dá bhrí sin i abairt mar “Tugann sé abairt SQL ar ais”, ba chóir “an” a bheith roimh “SQL” agus ní “a”.
- **Python** \- agus tú ag tagairt don teanga, caipitligh Python.
- **a bhaint amach, \*\*saincheapach**, **tosaithe**, srl. - bain úsáid as iarmhír “ize” Meiriceánach, ní “ise.”
- **fo-rang** \- is focal amháin é gan bhriathar, mar bhriathar (“fo-aicme an tsamhail sin”) agus mar ainmfhocal (“cruthaigh fo-aicme”).
- **an gréasán**, **creat gréasán** \- níl sé caipitlithe.
- **láithreán gréasáin** \- bain úsáid as focal amháin, gan caipitliú.

## Téarmaíocht Django-shonrach

- **samhail** \- níl sé caipitlithe.
- **teimpléad** \- níl sé caipitlithe.
- **URLConf** \- bain úsáid as trí litir chaipitealaithe, gan aon spás roimh “conf.”
- **amharc** \- níl sé caipitlithe.

## Treoirlínte maidir le comhaid RestructuredText

Rialaíonn na treoirlínte seo formáid ár ndoiciméad REst (ReStructuredText):

- I dteidil rannán, ní dhéanann caipitliú ach focail tosaigh agus ainmfhocail cheart.
- Fill an doiciméadú ag 80 carachtar ar leithead, mura bhfuil sampla cód i bhfad níos lú inléite nuair a roinntear thar dhá líne, nó ar chúis mhaith eile.
- Is é an rud is mó atá le coinneáil i gcuimhne agus tú ag scríobh agus a chur in eagar doiciméid ná is fearr an marcáil shéimeantach is féidir leat a chur leis. Mar sin:

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

  Níl sé beagnach chomh cabhrach le:

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

  Tá sé seo toisc go nginfidh Sphinx naisc cheart don dara ceann, rud a chabhraíonn go mór le léitheoirí.

  Is féidir leat an sprioc a réamhriú le `~` (sin tilde) chun ach an “giotán deireanach” den chosáin sin a fháil. Mar sin, taispeánfaidh ``:mod: `~django.contrib.auth`` nasc leis an teideal “auth”.
- Úsáid: MOD: ~sphinx.ext.intersphinx chun tagairt a dhéanamh do dhoiciméadú Python agus Sphinx.
- Cuir `.. code-block::<lang>` le bloic litriúla ionas go dtabharfar aird orthu. Is fearr leat brath ar aibhsiú uathoibríoch ag baint úsáide as `::` (dhá cholún). Tá an buntáiste aige seo, má tá roinnt comhréireachta neamhbhailí sa chód, nach gcuirfear béim air. Cuirfear `.. code-block:: python` leis, mar shampla, aird a tharraingt in ainneoin comhréireachta neamhbhailí.
- Chun inléiteacht a fheabhsú, bain úsáid as `.. áireamh:: Teideal tuairisciúil` seachas `.. nóta::`. Úsáid na boscaí seo go coigilteach.
- Úsáid na stíleanna ceannteideal seo:

  ```rst
  ===
  One
  ===

  Two
  ===

  Three
  -----

  Four
  ~~~~

  Five
  ^^^^
  ```
- Use [`:rfc:`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-rfc) to reference a Request for Comments (RFC) and
  try to link to the relevant section if possible. For example, use
  `` :rfc:`2324#section-2.3.2` `` or
  `` :rfc:`Custom link text <2324#section-2.3.2>` ``.
- Úsáid: rst:Role:  20 #easter -egg\`\` nó ``:pep: `Uibheacha Cásca``.
- Úsáid: rst:Role: :mimetype: \<mimetype\>\`chun tagairt a dhéanamh do Cineál MIME mura luaitear an luach le haghaidh sampla cód.
- \<envvar\>Úsáid: rst:Role: :envvar: \`chun tagairt a dhéanamh d'athróg comhshaoil. \<envvar\>B'fhéidir go mbeidh ort tagairt a shainiú don doiciméadú don athróg comhshaoil sin ag baint úsáid:rst:dir: \`.. envvar::.
- Use [`:cve:`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-cve) to reference a Common Vulnerabilities and
  Exposures (CVE) identifier. For example, use `` :cve:`2019-14232` ``.
- When documenting Python objects (classes, methods, attributes, etc.) using
  [Sphinx directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) such as `.. class::`, `.. method::`, and
  `.. attribute::`, all content must be properly indented to ensure correct
  rendering and to support features like automatic table of contents
  generation.

  Follow these rules:

  - The 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
    additional 4 spaces of indentation to maintain hierarchy.
  - Field lists (such as `:param:`, `:returns:`, etc.) must align with the
    directive's content level.

  Example:

  ```rst
  .. class:: MyClass

      A brief description of the class.

      .. method:: my_method(arg1, arg2)

          Method description.

          :param arg1: Description of the first parameter
          :param arg2: Description of the second parameter

      .. attribute:: my_attribute

          Attribute description.
  ```

## Marcáil Django-shonrach

Besides:ref: Marcáil ionsuite Sphinx \<sphinx:rst-index\>, sainmhíníonn doiciméid Django roinnt aonaid tuairiscithe breise:

- Socruithe:

  ```rst
  .. setting:: INSTALLED_APPS
  ```

  Chun nasc a dhéanamh le socrú, bain úsáid as ``:setting: `INSTALLED_APPS``.
- Clibeanna Teimpléad:

  ```rst
  .. templatetag:: regroup
  ```

  Chun nasc a dhéanamh, bain úsáid as ``:ttag: `athghrúpa``.
- Scagairí Teimpléad:

  ```rst
  .. templatefilter:: linebreaksbr
  ```

  Chun nasc a dhéanamh, bain úsáid as ``:tfilter: `linebreaksbr``.
- Cuardaigh réimse (ie foo.objects.filter (bar\_\_exact=what) ):

  ```rst
  .. fieldlookup:: exact
  ```

  Chun nasc a dhéanamh, bain úsáid as `` :lookup: `exact` ``.
- Orduithe django-admin :

  ```rst
  .. django-admin:: migrate
  ```

  Chun nasc a dhéanamh, bain úsáid as ``:djadmin: `migrate``.
- Roghanna líne ordaithe django-admin :

  ```rst
  .. django-admin-option:: --traceback
  ```

  Chun nasc a dhéanamh, bain úsáid as ``:option: `command_name --traceback`` (nó fág `command_name` do na roghanna atá roinnte ag gach ordú mar `--verbosity`).
- Naisc le ticéid Trac (curtha in áirithe de ghnáth le haghaidh nótaí scaoilte paiste)

  ```rst
  :ticket:`12345`
  ```

Úsáideann doiciméadú Django treoir saincheaptha `console` chun samplaí líne ordaithe a dhoiciméadú lena mbaineann ```django-admin ``, `manage.py```, python\`, srl.). Sa dhoiciméadú HTML, tugann sé UI dhá chluaisín, le cluaisín amháin ag taispeáint pras ordaithe i stíl Unix agus an dara cluaisín a thaispeánann pras Windows.

Mar shampla, is féidir leat an blúire seo a athsholáthar:

```rst
use this command:

.. code-block:: console

    $ python manage.py shell
```

leis an gceann seo:

```rst
use this command:

.. console::

    $ python manage.py shell
```

Tabhair faoi deara dhá rud:

- De ghnáth cuirfidh tú in ionad teagmhálacha an treoir `.. code-block:: console`.
- Ní gá duit ábhar iarbhír an sampla cód a athrú. Scríobhann tú é fós ag glacadh le timpeallacht Unix-y (ie siombail pras `` `'$' ``, `/` mar dheighilteoir comhpháirteanna cosáin an chórais chomhaid, srl.)

Tabharfaidh an sampla thuas bloc sampla cód le dhá chluaisín. Taispeánfaidh an chéad cheann:

```console
$ python manage.py shell
```

(Níl aon athruithe ar an méid a rinneadh `.. code-block:: console`).

Taispeánfaidh an dara ceann:

```doscon
...\> py manage.py shell
```

## Gnéithe nua a dhoiciméadú

Is é ár mbeartas maidir le gnéithe nua:

> Ba cheart gach doiciméadú ar ghnéithe nua a scríobh ar bhealach a shainíonn go soiléir na gnéithe nach bhfuil ar fáil ach i leagan forbartha Django. Glac leis go bhfuil léitheoirí doiciméadaithe ag baint úsáide as an eisiúint is déanaí, ní as an leagan forbartha.

Is é an bealach is fearr linn chun gnéithe nua a mharcáil ná doiciméadú na ngnéithe a réamh-mheas le: “`.. leaganadded:: X.Y`”, agus líne bán éigeantach agus cur síos roghnach (curtha) ina dhiaidh sin.

Ba chóir feabhsuithe ginearálta nó athruithe eile ar na APIs ar chóir béim a thabhairt ar an treoir “`.. versionmodified:: X.Y`” a úsáid (leis an bhformáid chéanna leis an `leaganadded` a luaitear thuas.

Ba chóir go mbeadh na bloic leaganaddaí agus leaganathraithe seo “féin-chuimsitheach.” Is é sin le rá, ós rud é nach gcoinnímid na nótaí seo ach ar feadh dhá eisiúint, tá sé go deas a bheith in ann an t-anótáil agus a ábhar a bhaint gan an téacs máguaird a athluchtú, a athshlánú nó a chur in eagar. Mar shampla, in ionad an tuairisc iomlán ar ghné nua nó athraithe a chur i mbloc, déan rud éigin mar seo:

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

Cuir na nótaí anótála athraithe ag bun roinn, ní an barr.

Chomh maith leis sin, seachain tagairt a dhéanamh do leagan ar leith de Django lasmuigh de bhloc ``leaganaded` nó `leaganathraithe``. Fiú laistigh de bhloc, is minic a bhíonn sé iomarcach é sin a dhéanamh mar a léiríonn na hanótaí seo mar “Nua i Django AB:” agus “Athraithe i Django AB”, faoi seach.

Má chuirtear feidhm, tréith, srl leis, tá sé ceart go leor freisin anótáil versionadded a úsáid mar seo:

```rst
.. attribute:: Author.middle_name

    .. versionadded:: A.B

    An author's middle name.
```

Is féidir linn an anótáil `.. leaganadded:: A.B` a bhaint gan aon athruithe insinte nuair a thagann an t-am.

## Íoslaghdú íomhánna

Comhbhrú íomhá a bharrfheabhsú nuair Maidir le comhaid PNG, bain úsáid as advpng\` OptiPNG agus AdvanceComp:

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

*Windows*

```doscon
...\> 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"`
```

Tá sé seo bunaithe ar leagan OptiPNG 0.7.5. Féadfaidh leaganacha níos sine gearán a dhéanamh faoi go bhfuil an rogha `-strip all` caillteanach.

## Sampla

Le haghaidh sampla tapa den chaoi a n-oireann sé go léir le chéile, smaoinigh ar an sampla hipitéiseach seo:

- Ar dtús, d'fhéadfadh leagan amach foriomlán mar seo a bheith ag an doiciméad ref/settings.txt \`:

  ```rst
  ========
  Settings
  ========

  ...

  .. _available-settings:

  Available settings
  ==================

  ...

  .. _deprecated-settings:

  Deprecated settings
  ===================

  ...
  ```
- Ansin, d'fhéadfadh rud éigin mar seo a bheith sa doiciméad topics/settings.txt :

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

  Úsáidimid an eilimint trasthagartha Sphinx: Rst: Role: doc nuair is mian linn nasc a dhéanamh le doiciméad eile ina iomláine agus an eilimint:rst:role: ref nuair is mian linn nasc a dhéanamh le suíomh treallach i ndoiciméad.
- Ansin, tabhair faoi deara conas a ndéantar na socruithe anótáilte:

  ```rst
  .. setting:: ADMINS

  ADMINS
  ======

  Default: ``[]`` (Empty list)

  A list of all the people who get code error notifications...
  ```

  Marcálann sé seo an ceanntásc seo a leanas mar an sprioc “canónach” don shocrú ```ADMINS`. Ciallaíonn sé seo aon uair a labhraím faoi ``ADMINS```, is féidir liom tagairt a dhéanamh air ag baint úsáide as ``:setting: `ADMINS``.

Sin go bunúsach mar a luíonn gach rud le chéile.

## Aistriú doicimé

Féach:ref: An doiciméadú Django a logánú \<translating-documentation\>\`más mian leat cabhrú leis an doiciméad a aistriú go teanga eile.

## `django-admin` leathanach fear

Is féidir le Sphinx leathanach láimhe a ghiniúint don ordú:doc: django-admin \</ref/django-admin\>. Tá sé seo cumraithe i docs/conf.py\`. Murab ionann agus aschur doiciméadaithe eile, ba chóir an leathanach fear seo a áireamh i stóras Django agus na heisiúintí mar docs/man/django-admin.1\`. Ní gá an comhad seo a nuashonrú agus an doiciméad á nuashonrú, mar go ndéantar é a nuashonrú uair amháin mar chuid den phróiseas scaoilte.

To generate an updated version of the man page, in the `docs` directory, run:

```console
$ make man
```

*Windows*

```doscon
...\> make.bat man
```

The new man page will be written in `docs/_build/man/django-admin.1`.