Re: Moving docs in-repo

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