Közreműködés a Weblate dokumentációban

Szívesen látjuk, ha bármelyik dokumentációs oldalt javítja vagy bővíti. Ezt legegyszerűbben a jobb felső sarokban található Oldal szerkesztése gombra kattintva teheti meg.

Dokumentációs irányelvek

Az alábbi elveket tartsa szem előtt írás közben:

  1. Ne töröljön olyan részt a dokumentációból, amely még érvényes.

  2. Használjon világos, könnyen érthető nyelvezetet. Ez technikai dokumentáció – nem vers. Ne feledje, hogy nem minden olvasó anyanyelve az angol.

  3. Ha valamiben nem biztos, bátran kérdezzen. Ha szerkesztés közben kérdése merül fel egy funkcióval kapcsolatban, ne módosítsa annak leírását, amíg nem kapott választ. Vagy módosítson vagy kérdezzen – a kettőt egyszerre ne tegye.

  4. Ellenőrizze a módosításait úgy, hogy végrehajtja az útmutatóban szereplő lépéseket.

  5. A módosításokat kis, áttekinthető részekre bontva küldje be, hogy az ellenőrzés és az összevonás gyorsabb és egyszerűbb legyen.

  6. Ha egy nagyobb cikket szeretne újrafogalmazni és átszerkeszteni, tegye ezt két lépésben:

    1. Először végezze el az újrafogalmazást

    2. Miután az átírás ellenőrzésre és elfogadásra került, külön PR-ben (módosítási kérelemben) módosítsa a bekezdések szerkezetét.

A dokumentáció helyi szerkesztése és fordítása

A dokumentáció helyben is szerkeszthető és felépíthető. A Python csomagkövetelmények a docs függőségi csoportban találhatók a pyproject.toml fájlban. Az építést (build) a ci/run-docs eszközzel végezheti el.

Tipp

A dokumentáció építéséhez szükséges a graphviz telepítése is.

A dokumentáció fordítása

A dokumentáció fordítása elérhető itt: translate the docs.

Jogosultságok, ellenőrzések, kiegészítők és automatikus javaslatok dokumentálása

Számos dokumentációs szakasz sablonokat használ, amelyek közvetlenül a kódból generálódnak. A következő adminisztrációs parancsok érhetők el:

Ezek a parancsok mind reStructuredText formátumban adnak vissza sablonokat, amelyeket a dokumentáció készítéséhez használunk fel. A legegyszerűbb módja a dokumentáció módosításának, ha vizuális összehasonlítást (diff) használ a szerkesztőjében.