> Git approach is no way to go for us because all the documentation has to be hosted on ASF side
Well, our Git repository [1] is hosted by ASF, isn't it? GitHub pages just generates HTML from MarkDown via Jekyll [2] static site generator. I understand the concern about GitHub pages, though. And Igor is right about different versions, seems like it may be not so easy with GH pages. So I propose to use Jekyll, but do not use GitHub pages: * Keep documentation in our Git repository in MarkDown format * Generate HTML when release comes out and upload it to ignite.apache.org (same as we do for API docs [3]) Seems to be easy enough. The hardest part is to come up with a good template. Thoughts? [1] https://git-wip-us.apache.org/repos/asf?p=ignite.git [2] https://jekyllrb.com/ [3] https://ignite.apache.org/releases/1.8.0/javadoc/ On Tue, Apr 11, 2017 at 7:09 PM, Denis Magda <dma...@apache.org> wrote: > Pavel, > > I totally agree that it’s becoming more and more inconvenient to run the > documentation on readme.io <http://readme.io/>. At the same time the Git > approach is no way to go for us because all the documentation has to be > hosted on ASF side. Presently we violate this policy and I look forward we > fix it pretty soon. > > So, in general, all the documentation content has to become a part of > Apache Ignite site and available from there. Here are some of the examples > of another ASF projects: > http://spark.apache.org/docs/2.1.0/ <http://spark.apache.org/docs/2.1.0/> > https://zeppelin.apache.org/contribution/documentation.html < > https://zeppelin.apache.org/contribution/documentation.html> > https://hadoop.apache.org/docs/r2.7.2/ <https://hadoop.apache.org/ > docs/r2.7.2/> > > Are you aware of any ready-to-be-used documentation libs that can be > easily reused by us? > > — > Denis > > > On Apr 11, 2017, at 2:02 AM, Pavel Tupitsyn <ptupit...@apache.org> > wrote: > > > > Igniters, > > > > Currently we host documentation on > > apacheignite.readme.io (and also apacheignite-net.readme.io, > > apacheignite-cpp.readme.io, apacheignite-mix.readme.io, etc). > > > > readme.io has a lot of problems mostly due to lack of proper version > > control: > > * Each "version" is just a copy. When fixing something, you have to > update > > all versions. > > * No good way to review changes. > > * "Propose edit" functionality is a joke. You can only accept or reject > an > > edit, no way to communicate with contributor, etc > > > > GitHub Pages solves all these problems: > > https://github.com/blog/2233-publish-your-project- > documentation-with-github-pages > > > > Basically, we'll have a separate folder in our Git repository where > > documentation is stored in markdown format. > > This way the process for updating docs is exactly the same as any other > > code change. > > Pull request with new feature can contain the docs for this feature, and > so > > on. > > > > Thoughts? > >
