At Calcite we have a simple approach that Arrow could mimic. We keep our documentation under the source tree in .md (GitHub markdown) format and we use Jekyll to generate into the svn repo that backs the Apache web site. Due to the markdown format it’s easy for committers and non-committers to write documentation, they can test using a local Jekyll instance, non-committers can submit a pull request, and it’s not much effort for a committer to re-generate and commit the web site.
You can also easily generate javadoc etc. into the same svn tree. Instructions here: https://github.com/apache/calcite/blob/master/site/README.md <https://github.com/apache/calcite/blob/master/site/README.md> Julian > On Dec 21, 2016, at 11:35 AM, Wes McKinney <wesmck...@gmail.com> wrote: > > hi folks, > > Our lack of organized documentation outside README documents on GitHub > is making it harder for people to pick up and use the project. What's > the easiest way to set up publishing tools that committers can access, > so we can add a /docs page on http://arrow.apache.org/, or links to > the specific Java/C++/Python documentation? > > Uwe set up http://pyarrow.readthedocs.io/en/latest/, but it would be > better to have this hosted from the apache.org site. Let me know if > there are other ideas! > > best > Wes
