OOjs UI's PHP docs should be auto-generated
Closed, ResolvedPublic
Actions

Assigned To

Authored By

	cscott
	Oct 23 2014, 8:58 PM

Description

Mediawiki has autogenerated JS and PHP docs at:
http://doc.wikimedia.org/mediawiki-core/master/php
http://doc.wikimedia.org/mediawiki-core/master/js

OOjs UI currently has docs at:
https://doc.wikimedia.org/oojs-ui/master/

These should be split into PHP and JS sections like for core.

There should be a Jenkins job which runs doxygen with a Doxyfile present at the root of the repo which updates doc.wikimedia.org. Look at jenkins:tools/mwcore-docgen.sh which is triggered by the mediawiki-core-doxygen-publish job.

hashar: cscott: I would go with a configuration file named 'Doxyfile' at the root of the repository and a thin JJB job template that just invokes Doxygen
hashar: cscott: that would let dev easily tweak the doxygen configuration without having to make a JJB conf change and refresh the job

Version: unspecified
Severity: normal

Details

Reference: bz72454

	Subject	Repo	Branch	Lines +/-
	Add link to OOUI PHP documentation	integration/docroot	master	+6 -1
	Add 'oojs-ui-doxygen-publish' job	integration/config	master	+19 -2

Customize query in gerrit

Related Objects
Search...

Status	Assigned	Task
Resolved	Legoktm	T74454 OOjs UI's PHP docs should be auto-generated
Resolved	hashar	T73062 doc.wikimedia.org: Generate documentation for release tags (tracking)
Resolved	hashar	T75991 publish jobs should support branch filtering for postmerge and still be triggerable via publish
Declined	None	T76003 zuul-cloner does not support Ref events
Resolved	thcipriani	T96390 Allow ref-updated listener to filter out tag deletions

Event Timeline

• bzimport raised the priority of this task from to Medium.Nov 22 2014, 3:46 AM

• bzimport added a project: OOUI.

• bzimport set Reference to bz72454.

cscott created this task.Oct 23 2014, 8:58 PM

gerritadmin wrote:

Change 168490 had a related patch set uploaded by Cscott:
Conf for doxygen based PHP doc

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

gerritadmin wrote:

Change 168490 merged by jenkins-bot:
Conf for doxygen based PHP doc

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

Does this now need a jenkins config change?

(In reply to James Forrester from comment #3)

Does this now need a jenkins config change?

Definitely :-)

I wrote an overview of the architecture we are using to generate documentation on slave and have them ultimately published to doc.wikimedia.org. It has a very simple job template example: https://www.mediawiki.org/wiki/Continuous_integration/Documentation_generation

Some additional guidelines:

the job should be run on Trusty slaves using:

node: contintLabsSlave && UbuntuTrusty

use the zuul-cloner to clone the repository (see jjb/macro-scm.yaml) should be as simple as:

builders:
- - zuul-cloner: projects: "oojs/ui"
    
    The clone is made under $WORKSPACE/src/$ZUUL_PROJECT so the doxygen builder would be:
- shell: | cd src/$ZUUL_PROJECT doxygen

the output destination is defined in the Doxyfile. We could parse the file to figure it out but it is probably easier to just hardcode it for now:
- push-doc: docsrc: 'src/oojs/ui/docs/php' # path in the workspace docdest: 'oojs-ui/php' # destination under doc.wikimedia.org

A few culprits:

there is already some jsduck documentation published, probably want to namespace the path based on the language (php / js).
we do not have a shell helper yet to easily namespace by git branch / tag. IIRC there is some logic around hardcoded in the jsduck macro for it.

Later on we can refactor the resulting job template to make it reusable by other projects as well.

And I just found out on stackoverflow that we can probably override the destination directory used by doxygen using something like:

( cd $WORKSPACE/src/$ZUUL_PROJECT; cat Doxyfile ; echo "HTML_OUTPUT=$WORKSPACE/build/doc" ) | doxygen -

Thus the push-docs macro docsrc parameter can be hardcoded to "build/doc" :D

gerritadmin wrote:

Change 170012 had a related patch set uploaded by Hashar:
contint: Graphviz on Jenkins slaves

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

gerritadmin wrote:

Change 170012 merged by Dzahn:
contint: Graphviz on Jenkins slaves

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

Jdforrester-WMF moved this task from Backlog to Doing on the OOUI board.Nov 24 2014, 2:36 AM

Jdforrester-WMF renamed this task from OOjs UI: PHP docs should be auto-generated to PHP docs should be auto-generated.Dec 2 2014, 12:36 AM

Jdforrester-WMF set Security to None.

We can do it for branches, but not for tags currently :(

Jdforrester-WMF moved this task from Doing to Next-up on the OOUI board.Dec 11 2014, 10:57 PM

When this happens, please maintain a redirect from https://doc.wikimedia.org/oojs-ui/master to https://doc.wikimedia.org/oojs-ui/master/php.

In T74454#931711, @Krinkle wrote:

When this happens, please maintain a redirect from https://doc.wikimedia.org/oojs-ui/master to https://doc.wikimedia.org/oojs-ui/master/php.

Presumably you meant "…from https://doc.wikimedia.org/oojs-ui/master to https://doc.wikimedia.org/oojs-ui/master/js"?

In T74454#933517, @Jdforrester-WMF wrote:

In T74454#931711, @Krinkle wrote:

When this happens, please maintain a redirect from https://doc.wikimedia.org/oojs-ui/master to https://doc.wikimedia.org/oojs-ui/master/php.

Presumably you meant "…from https://doc.wikimedia.org/oojs-ui/master to https://doc.wikimedia.org/oojs-ui/master/js"?