Pavel, We all agree that the documentation should be in our GIT repo in either Markdown or AsciiDoc format. However, it is a very big undertaking to migrate it from readme and properly structure it. If anyone in the community would volunteer, would be great.
D. On Tue, Apr 11, 2017 at 9:36 PM, Pavel Tupitsyn <ptupit...@apache.org> wrote: > > 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? > > > > >
