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.

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

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.