What's the process for pushing documentation artifacts, once they're ready for publication?

We have some reasonable documentation at https://www.mediawiki.org/wiki/Continuous_integration/Documentation_generation

You might want to define a 'npm doc' command that would generate HTML out of your markdown and images in /doc/. The result could be sent to /build-doc/ and thus the job would be something like:

- job-template: 'restbase-doc-publish'
    node: contintLabsSlave && UbuntuTrusty
    triggers:
     - zuul
    builders:
     - assert-env-doc_subpath
     - zuul-cloner:
        projects: >
           mediawiki/services/restbase
     - shell:
        . /srv/deployment/integration/slave-scripts/bin/npm-set-env.sh
        node --version
        npm --version
        npm install
        rm -fR build-doc
        npm doc
     - doc-publish:
        docsrc: 'build-doc'
        docdest: 'mediawiki-core/$DOC_SUBPATH'

We should most probably make it a job template in Jenkins '{name}-npm-doc-publish' that would assume the project has a npm doc command and generate the doc at build-doc. Will make it trivial to add a job.

@hashar Awesome, that looks like what we need. Where do we put the job definition? Something like <project>/.jenkins.yml?

In T87702#1015946, @Jdouglas wrote:

@hashar Awesome, that looks like what we need. Where do we put the job definition? Something like <project>/.jenkins.yml?

That would be too easy :-D The jobs are defined in YAML definitions files which produces Jenkins jobs via a python utility. The process is described at http://www.mediawiki.org/wiki/CI/JJB

You can poke #wikimedia-releng about it, there should be people here able to assist with crafting a job.

I would really like us to have a very generic and dumb Jenkins job that would do the same on all repositories (ex: git clone && make docs && rsync build/docs). I have raised the topic on wikitech-l https://lists.wikimedia.org/pipermail/wikitech-l/2015-February/080670.html and filled T88999: Define entry point to generate documentation. Making it a blocker.

If there is no objection by next Monday, I will just use make docs as a convention and let developers catch up / match the convention.

Sounds good to me!

After a week on wikitech-l and barely any comment, make docs is adopted as an entry point to generate documentation. Could you provide a /makefile with a docs target please?

I am working on the Jenkins job template ( https://gerrit.wikimedia.org/r/#/c/191045/ ) and experimenting with MobileFrontend first ( https://gerrit.wikimedia.org/r/#/c/191046/ ).

Our API docs are already published as a swagger-ui sandbox on https://rest.wikimedia.org. We could hook up a static version of the same docs directly in RESTBase as well if there is demand for printable docs.

I'm not aware of any other docs that we'd want to publish to doc.wikimedia.org. Should we close this as resolved?

See also T87802: "Search the docs" that searches static documentation as well as on-wiki doc namespaces.

Resolved? Where is the RESTBase documentation at https://doc.wikimedia.org/ ?

Following recent developments, the publish job is now a lot simpler.

It basically needs only these macros:

- npm-install
- npm-run-doc
- doc-publish: ..

Excellent! That is a great example of tightly coupling the code and the documentation, I love it :) Much better than a static doc on doc.wikimedia.org which might end up being out of sync or never found by end users consuming the API.

Kudos!

Change 202418 had a related patch set uploaded (by Krinkle):
doc: Add link to RESTBase documentation

https://gerrit.wikimedia.org/r/202418

Change 202418 merged by jenkins-bot:
doc: Add link to RESTBase documentation

https://gerrit.wikimedia.org/r/202418