Reframe wptserve documentation
jugglinmike opened this issue · comments
Some information about the WPT server is currently hosted not at http://web-platform-tests.org but instead at https://wptserve.readthedocs.io/en/latest/. This separation makes it harder to find existing information and to decide where new information should be written.
Previously, it's been suggested that all of the content be relocated to http://web-platform-tests.org--see WPT/14648. Although the current organization is referred to as "mostly historical accident," maintaining some amount of intentional separation could be appropriate. I'm specifically thinking of the description of Python APIs like Server, Router and most of the "handlers" documentation. This information is important for WPT infrastructure maintainers, but it isn't likely to be relevant to a wider audience.
I think properly addressing this issue may involve persisting some of the content on the "readthedocs" domain and potentially re-writing other parts for the "test author" audience.
@Hexcles you opened the WPT issue; what do you think? @jgraham does this seem reasonable to you?
See also https://wptrunner.readthedocs.io/en/latest/ which is even more developer-facing docs.
Since that's also "orphaned", I grouped it in with gh-1, but it also has some problems from serving multiple audiences.
Cleanly delineating these issues is a little tough; thanks for trying to make sense of it all anyway :)
I think splitting developer & user docs might be a good idea. Developer docs can continue to be written in rST (yeah I know...) and hosted on readthedocs, while the more user-facing docs (for example, pipes) should be merged with web-platoform-tests.org. However, I'm a bit worried about having to maintain two doc pipelines and the potential divergence between them.
I wouldn't mind if all the documentation were written in rST. I sense hesitation from you both; do you think it presents a meaningful amount of friction?
I'm fine with rST (or in fact any commonly used markup languages), although it seems to have lost the battle among light-weight markup languages -- similarities with Markdown but with tons of differences in the details seems to make rST a bit error-prone and annoying to many developers. I'd argue that it probably doesn't matter for developer-facing docs, but for user-facing docs we might want to consider lowering the barrier to entry by choosing a more popular markup language with easy-to-use tools (especially good integration with GitHub) to allow small contributions like drive-by fixes from the public.
I'm dubious about the mixture of Markdown and rST; I'd rather keep everything in Markdown (especially now Sphinx supports it, which matters for Python stuff if we want to keep using autodoc), especially given Markdown has essentially "won".
I don't love rst either, making everything in markdown seems like a good idea if the tooling allows that.
But I'm not sure I understand the premise of this discussion. As far as I can tell we have three groups of relevant users
- Test authors who aren't writing
.pyscripts - Test authors who are writing
.pyscripts - Infrastructure developers
I think all the documentation for the first two groups needs to be in the same place, because those categories aren't fixed; people who today don't need to make novel handlers may need to for the next test they write, and having to find documentation on a different site is a problem.
For the third group docs online aren't terribly useful; you need to look at the source and once you're doing that can just read the relevant docstrings directly. So I don't mind where or indeed if we document things that group needs to know but the first two don't.
Therefore I'd argue that going forward we should ignore the readthedocs dcumentation, but ensure that everything required to write a .py handler is in the main documentation. That strongly suggests that eerything should be using the same format since it will be processed by the same toolchain.
We're concerned about duplication, since as currently written, the documentation for the first two groups is a subset of the documentation for the third group. Having said that, I just took a closer look at the content, and the division actually seems fairly clean:
| page | for test authors? | for maintainers? |
|---|---|---|
| introduction | no | yes |
| server | no | yes |
| router | no | yes |
| request | yes | yes |
| response | yes | yes |
| handlers | some (only Python) | yes |
| stash | yes | yes |
| pipes | some (only usage) | some (only API) |
I've attempted to reflect this distinction in gh-9.
As for markup language concerns, that patch depends on gh-7, which introduces Sphinx while tightly circumscribing the reliance on reStructured text.
For the third group docs online aren't terribly useful; you need to look at the source and once you're doing that can just read the relevant docstrings directly. So I don't mind where or indeed if we document things that group needs to know but the first two don't.
I strongly disagree. We have enough complexity that it should definitely be possible to have better documentation than just having people having to dig through the code and read docstrings.
The current developer documentation is generated from the docstrings and any docs that aren't generated from the docstrings are almost guaranteed to be out of date. So whilst I don't really object to "publish the docstrings somewhere" (i.e. pretty much the status quo), I also think the supposed value of that is not nearly as high as you're making out.