Page MenuHomePhabricator

Document process to add jsdoc to a repository
Open, Needs TriagePublic

Description

For new JavaScript projects, document the process to add jsdoc as a documentation tool and publish the output to doc.wikimedia.org.

I had the use case of adding JSDoc to a "new" repository (mediawiki/tools/api-testing - T236915) and could not find documentation about it. We have a jsduck wikipage that redirects to https://www.mediawiki.org/wiki/Manual:Coding_conventions/JavaScript#Documentation which still refers to jsduck with a note left mentioning it is pending the switch of mediawiki/core

Can we potentially have a JSDoc page for the new repositories / non mediawiki ones? Looks like it might be fairly simple based on a recent commit ( https://gerrit.wikimedia.org/r/c/jquery-client/+/626136 ), but I am afraid I don't understand everything.

Looks like we just need to add jsdoc as a dependency and provide a npm run doc script https://www.mediawiki.org/wiki/Continuous_integration/Entry_points#JavaScript_documentation and from there we can add the doc job in integration/config using:

zuul/layout.yaml
- name: mediawiki/tools/api-testing
  template:
    - name: node12-rundoc-docker
  publish:
    - generic-node12-docs-docker-publish

Which should publish the doc at https://doc.wikimedia.org/api-testing/master/ and we can then add to the frontpage via integration/docroot.git

I could not find a wiki page explaining how to introduce JSDoc on a repository, but I have found https://gerrit.wikimedia.org/r/c/jquery-client/+/626136 I have asked further information on the legendary task that aims to replace jsduck by jsdoc: T138401#7138812