ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dmitriy Setrakyan <dsetrak...@apache.org>
Subject Re: Move documentation from readme.io to GitHub pages
Date Wed, 12 Apr 2017 04:57:52 GMT
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 <ptupitsyn@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 <dmagda@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 <ptupitsyn@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?
> >
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message