Průběžná integrace/generování dokumentace

Dokumentace je automaticky generována a publikována na doc.wikimedia.org. Pro zvýšení flexibility a zabezpečení jsou statické weby generovány uvnitř instancí WMCS. The docs are then fetched from the instance to the CI production host, and pushed with rsync to the documentation host (doc.discovery.wmnet as of March 2022). Tato stránka dokumentuje pracovní postup, část technické implementace a jak definovat novou úlohu.

Zuul

Náš soubor rozložení Zuul (zuul/layout.yaml) reaguje na dva druhy událostí Gerrit , které odpovídají dvěma různým kanálům:

Akce Gerrit	Zuul pipeline	Popis
change-merged	postmerge	Když Gerrit začlení změnu
ref-updated	publish	Reference je změněna (tip změn větví, úpravy tagů)

ref-updated - může pokrýt slučované změny od aktualizace cílové větve, ale událost není spojena s číslem změny Gerrit, což nám brání v hlášení zpět do rozhraní Gerrit. Používáme tedy:

• postmerge - pipeline pro zpětné hlášení v Gerrit, aby uživatel věděl, že dokumentace byla vygenerována
• publish - pipeline, které zpracovává pouze aktualizace referencí odpovídající ^refs/tags/.

V obou případech (change-merged nebo ref-updated) spustíme stejnou úlohu pro generování dokumentace pro jakoukoli větev nebo značku. Proto potřebujeme jmenný prostor dokumentace pod https://doc.wikimedia.org na základě názvu větve nebo názvu značky. Informace se mezi událostmi přenášejí odlišně a reference se mezi aktualizacemi větve a značkami mírně liší. Logiku převodu nese funkce Zuul python, která se aplikuje na všechny úlohy publikování. Vloží do funkce Gearman (a tím do pracovního prostředí Jenkins) proměnnou DOC_SUBPATH, která představuje verzi.

Příklad:

• Změna sloučená na větvi REL1_35: DOC_SUBPATH = REL1_35
• refs/tags/1.35.0 aktualizované: DOC_SUBPATH = 1.35.0

Odkaz: Gerrit change 173049

Můžeme tedy znovu použít tento parametr DOC_SUBPATH ke snadnému jmennému prostoru úloh na verzi. Například https://doc.wikimedia.org/mediawiki-core/ má dokumentaci jak pro větve vydání (https://doc.wikimedia.org/mediawiki-core/REL1_37/), tak pro značky (https://doc.wikimedia.org/mediawiki-core/1.36.2).

Konfigurace pro vaše rozšíření MediaWiki nebo vzhled

Pokud chcete získat dokumentaci publikovanou z rozšíření nebo vzhledu MediaWiki, měli byste použít jednu ze standardních šablon (které fungují pro rozšíření i vzhledy, navzdory názvu):

• PHP: mwext-doxygen-publish
• JavaScript: extension-javascript-documentation

Poznámka: Pokud chcete publikovat obě dokumentace ke kódu PHP a JavaScript, budete muset použít nestandardní šablonu pro jeden, protože oba se pokusí použít stejný cílový adresář na doc.wikimedia.org. Místo toho použijte generic-node18-browser-coverage-publish pro JavaScript, který nebude v konfliktu.

Definice tvůrců úloh Jenkins

Jak bylo řečeno výše, neměli byste potřebovat zakázkovou práci, ale místo toho použijte ty běžné. Pokud však zjistíte, že potřebujete udělat něco neobvyklého, vytvořte, prosím, vzkaz na Phabricatoru, abychom vám mohli pomoci.

Většina logiky je definována v Jenkins Job Builder jjb/job-templates.yaml a dalších konfiguračních souborech.

V definici úlohy builder definuje, jaké kroky se mají provést. Poskytujeme makro tvůrce s názvem doc-publish, které se stará o přenos vygenerovaných souborů na webový server https://doc.wikimedia.org/. Chce to dva parametry:

1. docsrc - Adresář obsahující soubory dokumentace vzhledem k pracovnímu prostoru (bez koncového lomítka)
2. docdest - Adresář pod https://doc.wikimedia.org/.

Příklad definice Job:

# Bespoke PHP project
- job:
    name: myproject-php-publish
    node: Docker
    concurrent: false
    triggers:
     - zuul
    builders:
     - docker-log-dir
     - docker-src-dir
     - docker-run-with-log-cache-src:
         image: docker-registry.wikimedia.org/releng/doxygen:1.9.8-s2
     - doc-publish:
        docsrc: 'doc/html'
        docdest: myproject
    publishers:
     - teardown

# Bespoke JS project
- job:
    name: myproject-js-publish
    node: Docker
    triggers:
     - zuul
    builders:
     - setup
     - docker-run-with-log-cache-src:
        image: 'docker-registry.wikimedia.org/releng/node18-test:0.2.0-s2'
        args: 'doc'
     - doc-publish:
        docsrc: 'docs'
        docdest: myproject
    publishers:
     - teardown

To vyvolá skripty sestavení (doxygen a npm run doc) a zveřejní jejich výsledky (respektive v doc/html a docs) na https://doc.wikimedia.org/myproject/.

Pro jmenný prostor dokumentace na základě verze projektu použijte Zuul vygenerovaný DOC_SUBPATH (odvozený z názvu větve nebo značky). Jednoduše jej vložte do parametru docdest. Budete muset vyvolat tvůrce assert-env-doc_subpath. Příklad pro MediaWiki (úloha mediawiki-core-doxygen-publish):

- job:
    name: 'mediawiki-core-doxygen-publish'
    builders:
     - assert-env-doc_subpath
     - zuul-cloner:
         projects: >
             mediawiki/core
             mediawiki/vendor
     # Build the documentation under /build/doc
     - shell: |
         rm -rf build/doc
         mkdir -p build/doc
         TARGET_BASEDIR="$WORKSPACE/build/doc" /srv/deployment/integration/slave-scripts/tools/mwcore-docgen.sh
     # Publish from build/doc to mediawiki-core/$DOC_SUBPATH/php'
     - doc-publish:
         docsrc: 'build/doc'
         docdest: 'mediawiki-core/$DOC_SUBPATH/php'

Toto publikuje dokumentaci na https://doc.wikimedia.org/mediawiki-core/master/php/ a také publikuje dokumentaci větve vydání, jako je https://doc.wikimedia.org/mediawiki-core/REL1_34/php/, a označené verze, jako je https://doc.wikimedia.org/mediawiki-core/1.34.0/php/

Architektura

Přehled architektury a runbooky najdete v wikitech:Doc.wikimedia.org

Související odkazy

• Průběžná integrace/vstupní body popisuje konvence pro automatizaci rozšíření. Pokud se při vývoji svého rozšíření budete řídit těmito pokyny, pak (se spoustou CI wizardry) proběhnou testy a dokumentace se generuje "automaticky".
• GitLab/Publishing docs