I hate to be that guy, but mentors warned this very project no to do this in the first place. At least once [1] on the dev@, and a few times off-line
[1] https://is.gd/ZRPOrH Cos -- Take care, Konstantin (Cos) Boudnik 2CAC 8312 4870 D885 8616 6115 220F 6980 1F27 E622 Disclaimer: Opinions expressed in this email are those of the author, and do not necessarily represent the views of any company the author might be affiliated with at the moment of writing. On Tue, Apr 11, 2017 at 9:57 PM, Dmitriy Setrakyan <dsetrak...@apache.org> wrote: > 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? >> > >> > >>
