Closed stefanotorresi closed 7 years ago
aww, totally missed that!
so, to sum it up, splitting the documentation will be done.
what is up to debate is the toolchain, and how, when and in what form the docs should be shipped with the components.
@weierophinney proposed bookdown. The main point for it is that it would allow developers to browse the docs of any given component offline, while also allowing to have a central repo that compiles each component docs into a full manual. All this while using just PHP and Markdown, which don't need any tool that a user is not necessarily familiar with (which is arguably not the case for the current RST toolchain).
I personally find this solution very promising. I like the ability to either browse the docs quickly by glancing at a markdown file (either offline or in github), or browse them offline after compiling in HTML via a straightforward PHP cli command.
I also think that the markdowns should be provided with the components regardless (so /docs
should not be export-ignored via .gitattributes
).
Lastly, I think compiled docs should be committed in the repo only if we opt for github pages.
@stefanotorresi I opened the PR on Diactoros:
This repo, however, has a lot of history, and no code. :)
Now that discussion has died down, I'm also talking with @GeeH, as he has volunteered to assist with documentation, particularly during this early phase of the split components. I'll update this post soon wiht details of that discussion.
Our consensus on reviewing the various toolchains is that bookdown satisfies the largest set of requirements:
bookdown.json
file can be easily converted to the rtfd.org configuration format in order to allow rendering docs on that platform, if desired.Among the objections/concerns raised was whether or not we can accommodate things like syntax highlighting of code samples, and, in particular, adding line numbers and/or line highlights. Bookdown does not do this by default. However, tools like prism.js do, and can be part of the master template for rendering documentation. Since bookdown uses league/commonmark, we can likely even extend the code sample template to pull in information such as lines to highlight to include in the generated HTML.
Pandoc can convert from rst to github-flavored markdown already as well, which provides a relatively easy migration tool.
Our plans at this point:
bookdown.json
file for each component.bookdown.json
file contain references to each component.Gary has volunteered to do the initial steps, in part to help enforce initial consistency of the documentation.
:+1:
Where will be hosted the HTML version?
It's not confirmed yet but will be hosted by Zend somewhere.
Where will be hosted the HTML version?
In the same place as always: http://framework.zend.com/manual
Version 2.4 is a LTS release and the docs can be found at framework.zend.com (up to 2018). Why a different place for the next versions?
I wonder if will be some kind of continuos deployment so each merge automatically publish a new rendered version
I ask this because I'm not aware of any plan about this, but now that we have the sources split, shouldn't we split the docs too? I reckon this would be no easy task, but since the source split was done to ease maintenance, a centralized documentation repo is in contrast with this very aim, and will become cumbersome very quickly for component maintainers.
AFAIK the reason why we had a separate docs repo in the first place, was because the doc sources for every component were a undesirable overhead when downloading/cloning the central repo, but this is obviously a non-issue now.
So, whaddya think?