Cur le doiciméadú Weblate

Tá fáilte romhat an leathanach doiciméadaithe de do rogha féin a fheabhsú. Déan é go héasca trí chliceáil ar an gcnaipe Cuir in eagar ar GitHub sa chúinne uachtarach ar dheis den leathanach.

Treoirlínte maidir le doiciméadú

Tabhair meas ar na treoirlínte seo agus tú ag scríobh:

  1. Ná bain cuid den doiciméadú má tá sé bailí.

  2. Bain úsáid as teanga atá soiléir agus sothuigthe. Tá tú ag scríobh doiciméad teicneolaíochta, ní dán. Ní cainteoirí dúchais iad gach léitheoir doc, bí tuisceanach.

  3. Ná bíodh eagla ort fiafraí mura bhfuil tú cinnte. Má tá ort ceist a chur faoi ghné éigin agus tú ag déanamh eagarthóireachta, ná athraigh a dhoiciméid sula mbeidh an freagra agat. Ciallaíonn sé seo: Athraíonn tú nó iarrann tú. Ná déan an dá rud ag an am céanna.

  4. Fíoraigh do chuid athruithe trí ghníomhartha tuairiscithe a dhéanamh agus na doiciméid á leanúint.

  5. Seol PR le hathruithe i bpíosaí beaga chun é a dhéanamh níos éasca agus níos tapúla athbhreithniú agus cumasc a dhéanamh.

  6. Más mian leat struchtúr alt mór a athscríobh agus a athrú, déan é in dhá chéim:

    1. Athscríobh

    2. Nuair atá an athscríobh athbhreithnithe, snasta, agus cumaiscthe, athraigh struchtúr na míreanna i PR eile.

  7. Match heading underline and overline lengths to the title's source text, including any inline markup. The pre-commit checks enforce matching lengths.

An doiciméadú a thógáil go háitiúil

Is féidir doiciméadú a chur in eagar agus a thógáil go háitiúil freisin, tá na riachtanais Python sa ghrúpa spleáchais docs i pyproject.toml. Má úsáideann tú an timpeallacht forbartha iomlán cheana féin, is leor uv sync --all-extras --dev. I gcás oibre doiciméadaithe amháin, is leor uv sync --group docs.

Seo an sreabhadh oibre áitiúil molta:

make -C docs update-docs
./ci/run-docs

Tógálann an fillteán ci/run-docs an doiciméadú le rabhaidh a láimhseáiltear mar earráidí.

CI documentation, release notes, and linkcheck builds reuse cached intersphinx inventories. The Intersphinx inventories workflow refreshes them daily and can also be run manually from GitHub Actions on the default branch. Failed refreshes retain the last valid inventories and are reported as workflow failures.

Inventories are stored in docs/_build/intersphinx. Builds use upstream inventories when a local copy is missing, including after CI cache eviction or when adding an inventory URL. Local and Read the Docs builds do not require the cache. To refresh local copies for all documentation languages, run:

languages=$(uv run --no-project scripts/list-documentation-languages.py)
uv run python docs/_ext/intersphinx_cache.py --languages "${languages#languages=}"

The inventory cache does not eliminate network requests for checking destination pages during linkcheck builds.

Hint

Beidh ort freisin graphviz a shuiteáil chun an doiciméadú a thógáil.

Na cáipéisí a aistriú

Is féidir leat na doiciméid a aistriú.

Sleachta doiciméadachta ginte á nuashonrú

Úsáideann roinnt rannóga doiciméadachta teimpléid a ghintear ón gcód. Is é an bealach is fearr chun iad a athnuachan ná:

make -C docs update-docs

Athghiníonn an sprioc seo na blúiríní atá in úsáid ag an doiciméadú faoi láthair, lena n-áirítear:

  • imeachtaí breiseáin, breiseáin ionsuite, agus paraiméadair bhreiseáin choitianta

  • seirbhísí aistriúcháin meaisín

  • paraiméadair formáid comhaid agus táblaí gnéithe formáid comhaid

  • ceadanna agus róil ionsuite

  • seiceálacha agus bratacha seiceála

Coinnigh téacs atá á chothabháil de láimh ar an leathanach doiciméadachta tuismitheora seachas é a chur le sleachta uathghinte. Mar shampla, áirítear le Breiseáin trí chomhad ginte le haghaidh imeachtaí, breiseáin ionsuite, agus paraiméadair bhreiseán coitianta, agus coimeádtar breiseáin atá as dáta go díreach ar an leathanach.

Más gá duit cuid amháin a athghiniúint, tá na horduithe bainistíochta aonair doiciméadaithe i Orduithe bainistíochta, agus tá na horduithe beachta a úsáideann update-docs liostaithe i docs/Makefile.