Dokumentáció írása és felülvizsgálata

A Cadrumo egy spanyol adóbevallási alkalmazás. Az AEAT a külső spanyol adóhatóság. Ez az útmutató bemutatja, hogyan hajtson végre egy dokumentációs változtatást, és hogyan vigye végig a felülvizsgálaton. Négy dokumentációs felület létezik: a kódtár markdown-ja, a forráskódba ágyazott docstringek, és két generált referencia - az egyik az alkalmazásprogramozási felülethez (API), a másik a parancssori felülethez (CLI).

Válassza ki a megfelelő felületet

Hogy hol hajtja végre a változtatást, az attól függ, mit módosít:

  • A kódtár markdown-ja kézzel írott. Szerkessze közvetlenül a README-t vagy egy útmutatót a docs/ alatt.

  • A docstringek az API-referencia egyetlen forrása. Szerkessze a docstringet a forrásban, és hagyja, hogy a Sphinx (a dokumentációépítő eszköz) megjelenítse. Soha ne másoljon kézzel egy szignatúrát a szövegbe.

  • Az API-referenciát a dev.docs.apidocs eszköz generálja a forrásmodulokból. Csonkoldalakat (helykitöltő referenciafájlokat) ír; ne szerkessze ezeket az oldalakat kézzel - generálja őket újra.

  • A CLI-referenciát a parancsfából (a CLI-parancsok és -alparancsok teljes halmazából) generáljuk. Ne szerkessze; generálja újra az alábbi parancsokkal.

A generálási fogalmak meghatározása

Amikor generált dokumentációval dolgozik, értse meg a következő terminológiát:

  • apidocs: A dev.docs.apidocs parancssori eszköz, amely a dev/docs/apidocs/ helyen található. Ez a projekt API-referencia csonkjainak építője, amely bejárja a kódbázis modulfáját az API szerkezetének meghatározásához, és legenerálja a megfelelő referenciafájlokat.

  • csonk (stub): A referenciacsonk-oldal egy automatikusan generált, helykitöltő RestructuredText (.rst) fájl a docs/api/ alatt. Minden csonkfájl egy Python-modulnak vagy -csomagnak felel meg, és tartalmazza azokat az automodule direktívákat, amelyek utasítják a Sphinxet, hogy az élő docstringet a kódból húzza be. A csonkok be vannak illesztve a kódtárba, de soha nem szabad kézzel szerkeszteni őket.

A generált felületek újraépítéséhez és ellenőrzéséhez futtassa:

python -m dev.docs.apidocs scaffold  # writes the API stub pages
just docs-build                        # builds the full documentation site
just docs-serve                  # serves the site with live reload (auto-picks a free port)
just docs-check                  # validates cross-references, stubs, and CLI output

A just docs-serve megnyit egy előnézetet, amely újraépít és frissíti a böngészőt, valahányszor egy docs/ alatti oldal vagy egy src/cadrumo/ alatti docstring megváltozik. Minden interfészhez egy nem alapértelmezett porton kötődik (így egy konténer, VM vagy LAN-beli társ is elérheti), és automatikusan szabad portot választ; adja ki a just docs-serve 9000 parancsot egy port rögzítéséhez. Második futtatáskor a már futó előnézethez csatlakozik, ahelyett, hogy ütközne vele. Egy modul hozzáadásához vagy eltávolításához továbbra is szükség van a python -m dev.docs.apidocs scaffold parancsra a csonkkészlet frissítéséhez.

A just docs-check hibát jelez egy törött kereszthivatkozásnál, egy hiányzó csonknál vagy egy olyan parancshivatkozásnál, amely már nem egyezik a parancsokkal.

Egy szöveges változtatás végigvitele a felülvizsgálaton

A README vagy egy docs/ alatti útmutató változtatása szakaszos felülvizsgálaton megy keresztül. Minden szakasznak külön felülvizsgálója van, és mindegyik befejeződik, mielőtt a következő elkezdődne:

  1. Drótváz. Vázolja fel a dokumentumot címként és szakaszcélokként. Rendeljen minden oldalhoz egy Diataxis-típust - a Diataxis egy dokumentációs keretrendszer, amely négyféle kategóriába sorolja az oldalakat: oktatóanyag, útmutató, referencia vagy magyarázat.

  2. Finomítás. Egy projektkontextussal nem rendelkező felülvizsgáló csak a drótvázat olvassa el, és megerősíti, hogy egy újonnan érkező megértené, mit ad át az egyes szakaszok. Módosítsa mindaddig, amíg minden szakasz átmegy.

  3. Kontextus. A kutatók összegyűjtik a tényeket, parancsokat, elérési utakat és forráshelyeket, amelyekre az egyes szakaszoknak szükségük van.

  4. Fogalmazás. A szerzők az összegyűjtött kontextus és a projekt szövegstílus-szabályai alapján írják meg az egyes szakaszokat.

  5. Technikai felülvizsgálat. A felülvizsgálók minden parancsot, kapcsolót, elérési utat és osztálynevet ellenőriznek a kóddal szemben.

  6. Szerkesztői felülvizsgálat. Egy projektkontextussal nem rendelkező felülvizsgáló ugyanazon szövegstílus-szabályok alapján ellenőrzi a szöveget.

  7. Jóváhagyás. A változtatás akkor kerül be, amikor a technikai és a szerkesztői felülvizsgálat átmegy.

Tartsa külön a szerepeket

Tartsa a kutatást, a fogalmazást és a felülvizsgálatot külön kezekben. Amikor kontextust gyűjt, ne írja meg a végleges szöveget. Amikor szerző, az összegyűjtött kontextusból írjon, és ne találjon ki tényeket. Amikor szerkesztői minőség szempontjából vizsgál felül, kizárólag a dokumentumból dolgozzon, a kódbázis nélkül. Az elkülönítés minden megítélést őszintén tart.

Ne kódoljon folyamat-metaadatokat

A dokumentáció elérési útjai, fájlnevei és tartalma csak domén- és témaneveket hordoznak. Ne tegye beléjük a dokumentációs keretrendszert vagy a projektmenedzsment-folyamatot. Ez kizárja a hullám-, fázis- és lépésazonosítókat, a terv- és döntésirekord-azonosítókat, valamint az ügynök- vagy kampánycímkéket. Az olvasónak a terméket kell látnia, nem a folyamatot, amely felépítette.