- From: James Graham <james@hoppipolla.co.uk>
- Date: Fri, 25 Apr 2014 11:16:18 +0100
- To: Rebecca Hauck <rhauck@adobe.com>, "public-test-infra@w3.org" <public-test-infra@w3.org>
On 24/04/14 19:31, Rebecca Hauck wrote: > > > On 4/23/14, 7:49 AM, "James Graham" <james@hoppipolla.co.uk> wrote: > >> At present there is a split in our documentation between several places; >> testtwf-website is supposed to be the authoritative source, but actually >> it's not that well maintained. I suspect this is at least partially >> because of the high overhead for contributing; in order to update the >> documentation for e.g. testharness.js, or the in-browser runner, to >> reflect a code change you would have to make a second PR in the >> testtwf-website repo and wait for another round of review. In practice >> this hasn't been happening, so we need to make things easier. >> >> I suggest we try to move the documentation as close to the code as >> possible (i.e. in the same repo) and make the website generating code do >> the work of pulling in the right files. An obvious way to structure this >> would be to add the projects requiring documentation as submodules of >> testtwf-website. > > This makes a lot of sense for the documentation that is bound to code - > testharness.js, runner, etc. I donıt have any big objections to the rest > of the docs being submoduled in WPT, but Iıd point out that doc > contributors should still preview their changes as theyıd appear on the > site before they submit the PR. This means that they should still have the > testtwf-website Jekyll environment to be able to preview locally since the > Jekyll build cans sometimes can break for silly reasons. The situation we > want to avoid is having a PR merged from WPT that has build errors (or > even cosmetic/formatting problems that pass the build) and having the site > be broken. What would be the best way to enable this workflow? So the way I would like it to work is that w-p-t and other things are included as submodules of testtwf-website and when you update the submodule pointer you would have the chance to preview the documentation and ensure that nothing was broken. Ideally we could have a directory like resources/ with the submodules in and then have the files under /docs be wrappers that textually include files in the resources directory like """ --- layout: docs type: whatever title: testharness.js API documentation --- {% include ../resources/testharness.js/docs/api.md %} """ But I don't know if that's actually supported by Jekyll. Maybe it's possible to fake using symlinks Otherwise some preprocessing step might be needed, which I guess is going to be unpopular. Suggestions welcome.
Received on Friday, 25 April 2014 10:16:43 UTC