I just had a look over the Apache Calcite approach and I like it very much. Both, from a technical and the structural (i.e. keeping the website in the main repo). This will enable us to have the format spec on Github, let users edit the spec and the homepage via PRs and keep them both linked and in sync. The following steps to do come to my mind:
1. Copy the infrastructure from Calcite 2. Incorporate our current content into it (i.e. move the current landing page into the structure) 3. Either move the spec from "/format/" to "/site/format" or find a way to let jekyll also parse this directory. 4. Publish it after review. I would volunteer to do all this but would rather see some +1s before proceeding ;) -- Uwe L. Korn uw...@xhochy.com On Wed, Dec 21, 2016, at 11:16 PM, Julian Hyde wrote: > 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 >
