Page MenuHomePhabricator

Publish RESTBase documentation on doc.wikimedia.org
Closed, DeclinedPublic

Description

Write a post-merge job that generates documentation.

Depending on whether it makes sense to fragment by version inside or outside the generated documentation we can either publish the html artefact in a versioned directory, or let the documentation tool handle it.

E.g. for OOjs, we publish to doc.wikimedia.org/oojs/{version} where version is the git branch or release tag (master, v1.x, v.1.0.7). RESTBase could follow this, or (if meant to be reliable), let the versioning schema handle it and only publish the current version.

Event Timeline

Krinkle raised the priority of this task from to Needs Triage.
Krinkle updated the task description. (Show Details)
Krinkle added a subscriber: Krinkle.
Krinkle renamed this task from Publish restbase documentation on doc.wikimedia.org to Publish RESTBase documentation on doc.wikimedia.org.Jan 27 2015, 11:08 PM
Krinkle set Security to None.

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?

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

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?

GWicke lowered the priority of this task from High to Low.Mar 15 2015, 4:18 PM
GWicke moved this task from Blocked / others to Ready / next on the RESTBase board.
GWicke moved this task from Ready / next to Backlog on the RESTBase board.
GWicke claimed this task.

Resolving.

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

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

The documentation is published at http://rest.wikimedia.org/en.wikipedia.org/v1/?doc, where it also provides a sandbox environment to directly try the API. We could additionally consider generating static API docs from the same Swagger spec in the future, but don't have concrete plans to do so right now.

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

Qgil changed the task status from Resolved to Declined.EditedApr 7 2015, 5:38 PM

Then this task ("Publish RESTBase documentation on doc.wikimedia.org") is declined, because of the reasons explained above.

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

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