You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ignite.apache.org by Pavel Tupitsyn <pt...@apache.org> on 2017/04/11 09:02:56 UTC
Move documentation from readme.io to GitHub pages
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?
Re: Move documentation from readme.io to GitHub pages
Posted by Igor Sapego <is...@apache.org>.
Pavel,
I totally agree with you, but what about documentations for different
versions? How do you suppose to solve this problem with GitHub pages?
On Tue, Apr 11, 2017 at 12:02 PM, Pavel Tupitsyn <pt...@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?
>
Re: Move documentation from readme.io to GitHub pages
Posted by Prachi Garg <pg...@gridgain.com>.
I did a very shallow research on Jekyll. Work flow seemed similar to
Docusaurus but more flexible in terms of directory structure- how docs can
be placed in the repo (Docusaurus requires docs to be stored in a
particular directory structure), as well as sidebar menu ( Docusaurus does
not allow child pages). Additionally, if so many open source projects are
using Jekyll, then I think it's definitely worth a try.
-Prachi
On Tue, Apr 10, 2018 at 4:52 PM, Denis Magda <dm...@gridgain.com> wrote:
> Look into both Docusaraus and Jekyll from the usage perspective. Here is
> my summary:
>
> *Documentation Sources *
>
> Will be stored on GitHub. My preference is to store them in "ignite/docs"
> folder as many other ASF projects do (Spark [1], Flink [2] and Storm [3]).
> If we need to update the sources of an already released version, then we
> can create ignite-{version}-docs branch, edit it directly and generate HTML
> pages from it.
>
> *Versioning*
>
> Since the docs are stored in the main repo, a doc version will correspond
> to an Ignite version. If changes incorporated in the master version of the
> docs have to be merged to a previous version and redeployed on the site, we
> will use standard 'git' facilities to propagate the changes whenever is
> needed.
>
> *Documentation Deployment and Automation*
>
> Documentation engines usually go with a set of scripts that produce an
> HTML version of the docs out of the sources. In our scenario, we will use
> the scripts to convert the sources stored in GitHub to HTML pages stored in
> SVN repo of Ignite site. The docs' HTML pages will be hosted on
> ignite.apache.org.
>
> By default, the one has to run the scripts on a local machine to produce
> the HTML pages. However, nothing prevents us from tweaking the scripts and
> using them in a way that would do this on a fly - "a page has changed in
> sources"->"update site button is pressed"->"HTML is generated and
> automatically deployed to the site".
>
>
> Btw, *Prachi*, have you checked up Jekyll [4]? It's used by Spark, Flink,
> Storm, and even Github Pages. It's simpler than Docusarus and still gives a
> way to generate customized sites with navigation menus and table of
> contents: https://ci.apache.org/projects/flink/flink-docs-release-1.4/
>
>
> Does anyone else have any open questions we need to solve before starting
> a migration process?
>
>
>
> [1] https://github.com/apache/spark/tree/master/docs
> [2] https://github.com/apache/flink/tree/master/docs
> [3] https://github.com/apache/storm/tree/master/docs
> [4] https://github.com/jekyll/jekyll
>
> On Wed, Mar 21, 2018 at 6:15 PM, Dmitriy Setrakyan <ds...@apache.org>
> wrote:
>
>> On Wed, Mar 21, 2018 at 9:27 PM, Prachi Garg <pg...@gridgain.com> wrote:
>>
>> > We can store the project (Markdown & Docusaurus config files) in Git,
>> use
>> > Docusaurus to build html, and upload them to Ignite website.
>> >
>>
>> Sounds good!
>>
>
>
Re: Move documentation from readme.io to GitHub pages
Posted by Denis Magda <dm...@gridgain.com>.
Look into both Docusaraus and Jekyll from the usage perspective. Here is my
summary:
*Documentation Sources *
Will be stored on GitHub. My preference is to store them in "ignite/docs"
folder as many other ASF projects do (Spark [1], Flink [2] and Storm [3]).
If we need to update the sources of an already released version, then we
can create ignite-{version}-docs branch, edit it directly and generate HTML
pages from it.
*Versioning*
Since the docs are stored in the main repo, a doc version will correspond
to an Ignite version. If changes incorporated in the master version of the
docs have to be merged to a previous version and redeployed on the site, we
will use standard 'git' facilities to propagate the changes whenever is
needed.
*Documentation Deployment and Automation*
Documentation engines usually go with a set of scripts that produce an HTML
version of the docs out of the sources. In our scenario, we will use the
scripts to convert the sources stored in GitHub to HTML pages stored in SVN
repo of Ignite site. The docs' HTML pages will be hosted on
ignite.apache.org.
By default, the one has to run the scripts on a local machine to produce
the HTML pages. However, nothing prevents us from tweaking the scripts and
using them in a way that would do this on a fly - "a page has changed in
sources"->"update site button is pressed"->"HTML is generated and
automatically deployed to the site".
Btw, *Prachi*, have you checked up Jekyll [4]? It's used by Spark, Flink,
Storm, and even Github Pages. It's simpler than Docusarus and still gives a
way to generate customized sites with navigation menus and table of
contents: https://ci.apache.org/projects/flink/flink-docs-release-1.4/
Does anyone else have any open questions we need to solve before starting a
migration process?
[1] https://github.com/apache/spark/tree/master/docs
[2] https://github.com/apache/flink/tree/master/docs
[3] https://github.com/apache/storm/tree/master/docs
[4] https://github.com/jekyll/jekyll
On Wed, Mar 21, 2018 at 6:15 PM, Dmitriy Setrakyan <ds...@apache.org>
wrote:
> On Wed, Mar 21, 2018 at 9:27 PM, Prachi Garg <pg...@gridgain.com> wrote:
>
> > We can store the project (Markdown & Docusaurus config files) in Git, use
> > Docusaurus to build html, and upload them to Ignite website.
> >
>
> Sounds good!
>
Re: Move documentation from readme.io to GitHub pages
Posted by Dmitriy Setrakyan <ds...@apache.org>.
On Wed, Mar 21, 2018 at 9:27 PM, Prachi Garg <pg...@gridgain.com> wrote:
> We can store the project (Markdown & Docusaurus config files) in Git, use
> Docusaurus to build html, and upload them to Ignite website.
>
Sounds good!
Re: Move documentation from readme.io to GitHub pages
Posted by Prachi Garg <pg...@gridgain.com>.
We can store the project (Markdown & Docusaurus config files) in Git, use
Docusaurus to build html, and upload them to Ignite website.
On Tue, Mar 20, 2018 at 10:29 PM, Dmitriy Setrakyan <ds...@apache.org>
wrote:
> Does docusaurus work with GitHub only, or with Git in general? In Apache
> GitHub is used as a mirror of an internal Git repo, which is the primary
> source of data.
>
> D.
>
Re: Move documentation from readme.io to GitHub pages
Posted by Dmitriy Setrakyan <ds...@apache.org>.
Does docusaurus work with GitHub only, or with Git in general? In Apache
GitHub is used as a mirror of an internal Git repo, which is the primary
source of data.
D.
Re: Move documentation from readme.io to GitHub pages
Posted by Denis Magda <dm...@apache.org>.
Copied from the ticket.
*Feature*
*Docusaurus*
*GitBook*
*Free*
Yes (FaceBook open source project)
Yes (Free version only allows 5 contributors)
*Setup and Installation*
Easy installation and configuration steps.
Initial setup is easy; Need to look around for customization.
*Standard Markdown*
Yes
Yes
*Versioning*
Yes (automatic)
Yes (via github branching)
*Search*
Yes
Yes
*Table of contents for pages*
Yes (out-of-the-box)
No (Default theme does not support it; maybe availble through external
plugin)
*Support child pages*
No
Yes
*Allows website design customization*
Yes
Limited; Use external theme plugins.
*Top Nav bar & Footer*
Yes
No
*Live server(localhost) to view changes*
Yes
Yes
*Tab navigation on pages*
No tab navigation support out-of-the box.
Note: It is possible to create tabs using external React JS plugin or
implementing a React component. For example, React Native uses Docusaurus
and have implemented tabs-
http://facebook.github.io/react-native/docs/getting-started.html
No tab navigation support out-of-the box.
Note: It is possible to create tabs using external GitBook plugins.
*Publishing the website*
Publish the documentation site to Github pages or other static file hosts.
Publish the documentation site to git.gitbook.io (or custom domain) or
other static file hosts.
*Store all markdown files on github*
Yes
Yes
*Editor*
Use text editor. Alternatively, IntelliJ can be used, it has a plugin for
Markdown.
Provides desktop and online editor.
*Active support and development*
Yes. Facebook engineers are pretty responsive!
Hmm.. some people are wondering if they are still alive :-)
Prachi, thanks for the research and summary. I cast my ballot for
Docusaurus. It has much more prominent benefits over
GitBook such as a table of content, more advanced visual customization,
ability to edit from IntelliJ, and support by Facebook
engineers -- probably that's the way for Ignite to get installed at
Facebook in the future.
--
Denis
On Tue, Mar 20, 2018 at 4:38 PM, Prachi Garg <pg...@gridgain.com> wrote:
> I looked into Docusaurus and GitBook. I liked Docusaurus better because it
> allows publishing to github pages or other static files hosts, and various
> other features. My findings are mentioned in the ticket -
> https://issues.apache.org/jira/browse/IGNITE-7595 .
>
> On Fri, Feb 2, 2018 at 2:42 PM, Denis Magda <dm...@apache.org> wrote:
>
> > Looks promising. Thanks for sharing. Updated the ticket.
> >
> > —
> > Denis
> >
> > > On Feb 2, 2018, at 2:25 PM, Dmitriy Setrakyan <ds...@apache.org>
> > wrote:
> > >
> > > I think docusaurus.io could work for us. Denis, what do you think?
> > >
> > > On Fri, Feb 2, 2018 at 3:10 AM, endianignite <en...@gmail.com>
> > wrote:
> > >
> > >> I noticed that Facebook open-sourced a documentation platform last
> > month,
> > >> https://docusaurus.io/, which may be worth considering.
> > >>
> > >>
> > >>
> > >>
> > >>
> > >> --
> > >> Sent from: http://apache-ignite-developers.2346864.n4.nabble.com/
> > >>
> >
> >
>
Re: Move documentation from readme.io to GitHub pages
Posted by Prachi Garg <pg...@gridgain.com>.
I looked into Docusaurus and GitBook. I liked Docusaurus better because it
allows publishing to github pages or other static files hosts, and various
other features. My findings are mentioned in the ticket -
https://issues.apache.org/jira/browse/IGNITE-7595 .
On Fri, Feb 2, 2018 at 2:42 PM, Denis Magda <dm...@apache.org> wrote:
> Looks promising. Thanks for sharing. Updated the ticket.
>
> —
> Denis
>
> > On Feb 2, 2018, at 2:25 PM, Dmitriy Setrakyan <ds...@apache.org>
> wrote:
> >
> > I think docusaurus.io could work for us. Denis, what do you think?
> >
> > On Fri, Feb 2, 2018 at 3:10 AM, endianignite <en...@gmail.com>
> wrote:
> >
> >> I noticed that Facebook open-sourced a documentation platform last
> month,
> >> https://docusaurus.io/, which may be worth considering.
> >>
> >>
> >>
> >>
> >>
> >> --
> >> Sent from: http://apache-ignite-developers.2346864.n4.nabble.com/
> >>
>
>
Re: Move documentation from readme.io to GitHub pages
Posted by Denis Magda <dm...@apache.org>.
Looks promising. Thanks for sharing. Updated the ticket.
—
Denis
> On Feb 2, 2018, at 2:25 PM, Dmitriy Setrakyan <ds...@apache.org> wrote:
>
> I think docusaurus.io could work for us. Denis, what do you think?
>
> On Fri, Feb 2, 2018 at 3:10 AM, endianignite <en...@gmail.com> wrote:
>
>> I noticed that Facebook open-sourced a documentation platform last month,
>> https://docusaurus.io/, which may be worth considering.
>>
>>
>>
>>
>>
>> --
>> Sent from: http://apache-ignite-developers.2346864.n4.nabble.com/
>>
Re: Move documentation from readme.io to GitHub pages
Posted by Dmitriy Setrakyan <ds...@apache.org>.
I think docusaurus.io could work for us. Denis, what do you think?
On Fri, Feb 2, 2018 at 3:10 AM, endianignite <en...@gmail.com> wrote:
> I noticed that Facebook open-sourced a documentation platform last month,
> https://docusaurus.io/, which may be worth considering.
>
>
>
>
>
> --
> Sent from: http://apache-ignite-developers.2346864.n4.nabble.com/
>
Re: Move documentation from readme.io to GitHub pages
Posted by endianignite <en...@gmail.com>.
I noticed that Facebook open-sourced a documentation platform last month,
https://docusaurus.io/, which may be worth considering.
--
Sent from: http://apache-ignite-developers.2346864.n4.nabble.com/
Re: Move documentation from readme.io to GitHub pages
Posted by Pavel Tupitsyn <pt...@apache.org>.
Alexey, yes, cherry-pick to branches and update website for each version as
well (this can be automated with a script)
Still a bit cumbersome, but at least you don't have to make the same edit
multiple times.
On Fri, Feb 2, 2018 at 10:59 AM, Alexey Kuznetsov <ak...@apache.org>
wrote:
> Pavel,
>
> Do I correctly understand, that if I find a typo in docs, I should commit
> fix to master and cherry-pick to all relevant branches?
>
> On Fri, Feb 2, 2018 at 2:28 PM, Pavel Tupitsyn <pt...@apache.org>
> wrote:
>
> > I did some research for my blog some time ago, and proposal is:
> >
> > * Export markdown from Readme.io (tweak as necessary, code samples etc)
> > * Store markdown in git. Separate branch for each Ignite version
> > (ignite-2.3-docs, ignite-2.4-docs, etc). Future version is in master.
> > * Use Jekyll to generate HTML from markdown
> > * Host documentation on ignite.apache.org (upload is via SVN, any
> > committer
> > has rights, *changes are instant*)
> >
> > On Fri, Feb 2, 2018 at 2:05 AM, Denis Magda <dm...@apache.org> wrote:
> >
> > > Dmitriy,
> > >
> > > We will do a research before jumping off the readme.io <
> > http://readme.io/>
> > > train.
> > >
> > > In addition, to the technical issues outlined in the ticket, readme.io
> <
> > > http://readme.io/> doesn’t give a way to tell Google “Hey, Google,
> index
> > > only the latest docs' version! Ignore specific versions”. As a result,
> > the
> > > Internet is flooded with Ignite 1.1, 1.7, 1.9 versions of the pages
> that
> > > pop up at the top of the search. You know this annoying thing better
> than
> > > me :)
> > >
> > > —
> > > Denis
> > >
> > > > On Feb 1, 2018, at 1:39 PM, Dmitriy Setrakyan <dsetrakyan@apache.org
> >
> > > wrote:
> > > >
> > > > Guys, as I have been saying all along, we need to identify a
> > > documentation
> > > > system we want to move to. Once we do that, we can plan how to move
> off
> > > of
> > > > readme.
> > > >
> > > > Again, the most important benefit readme has is instantaneous
> > > documentation
> > > > update. However, on the downside, they do not integrate with Git
> well,
> > > and
> > > > ASF wants all its projects to keep the documentation in Apache Git.
> > > >
> > > > Does anyone have suggestions?
> > > >
> > > > D.
> > > >
> > > > On Thu, Feb 1, 2018 at 5:57 AM, Pavel Tupitsyn <ptupitsyn@apache.org
> >
> > > wrote:
> > > >
> > > >> Good news, Denis.
> > > >>
> > > >> By the way, readme.io uses some kind of markdown dialect, and they
> > have
> > > >> "export" feature,
> > > >> so it should be possible to move to some markdown-based system like
> > > Jekyll
> > > >> without too much hassle.
> > > >>
> > > >> On Thu, Feb 1, 2018 at 2:18 AM, Denis Magda <dm...@apache.org>
> > wrote:
> > > >>
> > > >>> Created a ticket. I think the time to move from readme.io <
> > > >>> http://readme.io/> has come. It’s becoming too challenging to live
> > > with
> > > >>> it:
> > > >>> https://issues.apache.org/jira/browse/IGNITE-7595 <
> > > >>> https://issues.apache.org/jira/browse/IGNITE-7595>
> > > >>>
> > > >>> —
> > > >>> Denis
> > > >>>
> > > >>>> On Apr 13, 2017, at 8:25 AM, Dmitriy Setrakyan <
> > dsetrakyan@apache.org
> > > >
> > > >>> wrote:
> > > >>>>
> > > >>>> On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <
> cos@apache.org
> > >
> > > >>> wrote:
> > > >>>>
> > > >>>>> 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
> > > >>>>>
> > > >>>>
> > > >>>> Cos, no doubt this had come up before (after all, we did have very
> > > good
> > > >>>> mentors during the incubation process).
> > > >>>>
> > > >>>> Unfortunately, for tasks like this it is never a good time. I hope
> > > >>> someone
> > > >>>> in the community picks it up, or at least gets started on it.
> > > >>>
> > > >>>
> > > >>
> > >
> > >
> >
>
>
>
> --
> Alexey Kuznetsov
>
Re: Move documentation from readme.io to GitHub pages
Posted by Alexey Kuznetsov <ak...@apache.org>.
Pavel,
Do I correctly understand, that if I find a typo in docs, I should commit
fix to master and cherry-pick to all relevant branches?
On Fri, Feb 2, 2018 at 2:28 PM, Pavel Tupitsyn <pt...@apache.org> wrote:
> I did some research for my blog some time ago, and proposal is:
>
> * Export markdown from Readme.io (tweak as necessary, code samples etc)
> * Store markdown in git. Separate branch for each Ignite version
> (ignite-2.3-docs, ignite-2.4-docs, etc). Future version is in master.
> * Use Jekyll to generate HTML from markdown
> * Host documentation on ignite.apache.org (upload is via SVN, any
> committer
> has rights, *changes are instant*)
>
> On Fri, Feb 2, 2018 at 2:05 AM, Denis Magda <dm...@apache.org> wrote:
>
> > Dmitriy,
> >
> > We will do a research before jumping off the readme.io <
> http://readme.io/>
> > train.
> >
> > In addition, to the technical issues outlined in the ticket, readme.io <
> > http://readme.io/> doesn’t give a way to tell Google “Hey, Google, index
> > only the latest docs' version! Ignore specific versions”. As a result,
> the
> > Internet is flooded with Ignite 1.1, 1.7, 1.9 versions of the pages that
> > pop up at the top of the search. You know this annoying thing better than
> > me :)
> >
> > —
> > Denis
> >
> > > On Feb 1, 2018, at 1:39 PM, Dmitriy Setrakyan <ds...@apache.org>
> > wrote:
> > >
> > > Guys, as I have been saying all along, we need to identify a
> > documentation
> > > system we want to move to. Once we do that, we can plan how to move off
> > of
> > > readme.
> > >
> > > Again, the most important benefit readme has is instantaneous
> > documentation
> > > update. However, on the downside, they do not integrate with Git well,
> > and
> > > ASF wants all its projects to keep the documentation in Apache Git.
> > >
> > > Does anyone have suggestions?
> > >
> > > D.
> > >
> > > On Thu, Feb 1, 2018 at 5:57 AM, Pavel Tupitsyn <pt...@apache.org>
> > wrote:
> > >
> > >> Good news, Denis.
> > >>
> > >> By the way, readme.io uses some kind of markdown dialect, and they
> have
> > >> "export" feature,
> > >> so it should be possible to move to some markdown-based system like
> > Jekyll
> > >> without too much hassle.
> > >>
> > >> On Thu, Feb 1, 2018 at 2:18 AM, Denis Magda <dm...@apache.org>
> wrote:
> > >>
> > >>> Created a ticket. I think the time to move from readme.io <
> > >>> http://readme.io/> has come. It’s becoming too challenging to live
> > with
> > >>> it:
> > >>> https://issues.apache.org/jira/browse/IGNITE-7595 <
> > >>> https://issues.apache.org/jira/browse/IGNITE-7595>
> > >>>
> > >>> —
> > >>> Denis
> > >>>
> > >>>> On Apr 13, 2017, at 8:25 AM, Dmitriy Setrakyan <
> dsetrakyan@apache.org
> > >
> > >>> wrote:
> > >>>>
> > >>>> On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <cos@apache.org
> >
> > >>> wrote:
> > >>>>
> > >>>>> 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
> > >>>>>
> > >>>>
> > >>>> Cos, no doubt this had come up before (after all, we did have very
> > good
> > >>>> mentors during the incubation process).
> > >>>>
> > >>>> Unfortunately, for tasks like this it is never a good time. I hope
> > >>> someone
> > >>>> in the community picks it up, or at least gets started on it.
> > >>>
> > >>>
> > >>
> >
> >
>
--
Alexey Kuznetsov
Re: Move documentation from readme.io to GitHub pages
Posted by Pavel Tupitsyn <pt...@apache.org>.
I did some research for my blog some time ago, and proposal is:
* Export markdown from Readme.io (tweak as necessary, code samples etc)
* Store markdown in git. Separate branch for each Ignite version
(ignite-2.3-docs, ignite-2.4-docs, etc). Future version is in master.
* Use Jekyll to generate HTML from markdown
* Host documentation on ignite.apache.org (upload is via SVN, any committer
has rights, *changes are instant*)
On Fri, Feb 2, 2018 at 2:05 AM, Denis Magda <dm...@apache.org> wrote:
> Dmitriy,
>
> We will do a research before jumping off the readme.io <http://readme.io/>
> train.
>
> In addition, to the technical issues outlined in the ticket, readme.io <
> http://readme.io/> doesn’t give a way to tell Google “Hey, Google, index
> only the latest docs' version! Ignore specific versions”. As a result, the
> Internet is flooded with Ignite 1.1, 1.7, 1.9 versions of the pages that
> pop up at the top of the search. You know this annoying thing better than
> me :)
>
> —
> Denis
>
> > On Feb 1, 2018, at 1:39 PM, Dmitriy Setrakyan <ds...@apache.org>
> wrote:
> >
> > Guys, as I have been saying all along, we need to identify a
> documentation
> > system we want to move to. Once we do that, we can plan how to move off
> of
> > readme.
> >
> > Again, the most important benefit readme has is instantaneous
> documentation
> > update. However, on the downside, they do not integrate with Git well,
> and
> > ASF wants all its projects to keep the documentation in Apache Git.
> >
> > Does anyone have suggestions?
> >
> > D.
> >
> > On Thu, Feb 1, 2018 at 5:57 AM, Pavel Tupitsyn <pt...@apache.org>
> wrote:
> >
> >> Good news, Denis.
> >>
> >> By the way, readme.io uses some kind of markdown dialect, and they have
> >> "export" feature,
> >> so it should be possible to move to some markdown-based system like
> Jekyll
> >> without too much hassle.
> >>
> >> On Thu, Feb 1, 2018 at 2:18 AM, Denis Magda <dm...@apache.org> wrote:
> >>
> >>> Created a ticket. I think the time to move from readme.io <
> >>> http://readme.io/> has come. It’s becoming too challenging to live
> with
> >>> it:
> >>> https://issues.apache.org/jira/browse/IGNITE-7595 <
> >>> https://issues.apache.org/jira/browse/IGNITE-7595>
> >>>
> >>> —
> >>> Denis
> >>>
> >>>> On Apr 13, 2017, at 8:25 AM, Dmitriy Setrakyan <dsetrakyan@apache.org
> >
> >>> wrote:
> >>>>
> >>>> On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <co...@apache.org>
> >>> wrote:
> >>>>
> >>>>> 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
> >>>>>
> >>>>
> >>>> Cos, no doubt this had come up before (after all, we did have very
> good
> >>>> mentors during the incubation process).
> >>>>
> >>>> Unfortunately, for tasks like this it is never a good time. I hope
> >>> someone
> >>>> in the community picks it up, or at least gets started on it.
> >>>
> >>>
> >>
>
>
Re: Move documentation from readme.io to GitHub pages
Posted by Denis Magda <dm...@apache.org>.
Dmitriy,
We will do a research before jumping off the readme.io <http://readme.io/> train.
In addition, to the technical issues outlined in the ticket, readme.io <http://readme.io/> doesn’t give a way to tell Google “Hey, Google, index only the latest docs' version! Ignore specific versions”. As a result, the Internet is flooded with Ignite 1.1, 1.7, 1.9 versions of the pages that pop up at the top of the search. You know this annoying thing better than me :)
—
Denis
> On Feb 1, 2018, at 1:39 PM, Dmitriy Setrakyan <ds...@apache.org> wrote:
>
> Guys, as I have been saying all along, we need to identify a documentation
> system we want to move to. Once we do that, we can plan how to move off of
> readme.
>
> Again, the most important benefit readme has is instantaneous documentation
> update. However, on the downside, they do not integrate with Git well, and
> ASF wants all its projects to keep the documentation in Apache Git.
>
> Does anyone have suggestions?
>
> D.
>
> On Thu, Feb 1, 2018 at 5:57 AM, Pavel Tupitsyn <pt...@apache.org> wrote:
>
>> Good news, Denis.
>>
>> By the way, readme.io uses some kind of markdown dialect, and they have
>> "export" feature,
>> so it should be possible to move to some markdown-based system like Jekyll
>> without too much hassle.
>>
>> On Thu, Feb 1, 2018 at 2:18 AM, Denis Magda <dm...@apache.org> wrote:
>>
>>> Created a ticket. I think the time to move from readme.io <
>>> http://readme.io/> has come. It’s becoming too challenging to live with
>>> it:
>>> https://issues.apache.org/jira/browse/IGNITE-7595 <
>>> https://issues.apache.org/jira/browse/IGNITE-7595>
>>>
>>> —
>>> Denis
>>>
>>>> On Apr 13, 2017, at 8:25 AM, Dmitriy Setrakyan <ds...@apache.org>
>>> wrote:
>>>>
>>>> On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <co...@apache.org>
>>> wrote:
>>>>
>>>>> 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
>>>>>
>>>>
>>>> Cos, no doubt this had come up before (after all, we did have very good
>>>> mentors during the incubation process).
>>>>
>>>> Unfortunately, for tasks like this it is never a good time. I hope
>>> someone
>>>> in the community picks it up, or at least gets started on it.
>>>
>>>
>>
Re: Move documentation from readme.io to GitHub pages
Posted by Dmitriy Setrakyan <ds...@apache.org>.
Guys, as I have been saying all along, we need to identify a documentation
system we want to move to. Once we do that, we can plan how to move off of
readme.
Again, the most important benefit readme has is instantaneous documentation
update. However, on the downside, they do not integrate with Git well, and
ASF wants all its projects to keep the documentation in Apache Git.
Does anyone have suggestions?
D.
On Thu, Feb 1, 2018 at 5:57 AM, Pavel Tupitsyn <pt...@apache.org> wrote:
> Good news, Denis.
>
> By the way, readme.io uses some kind of markdown dialect, and they have
> "export" feature,
> so it should be possible to move to some markdown-based system like Jekyll
> without too much hassle.
>
> On Thu, Feb 1, 2018 at 2:18 AM, Denis Magda <dm...@apache.org> wrote:
>
> > Created a ticket. I think the time to move from readme.io <
> > http://readme.io/> has come. It’s becoming too challenging to live with
> > it:
> > https://issues.apache.org/jira/browse/IGNITE-7595 <
> > https://issues.apache.org/jira/browse/IGNITE-7595>
> >
> > —
> > Denis
> >
> > > On Apr 13, 2017, at 8:25 AM, Dmitriy Setrakyan <ds...@apache.org>
> > wrote:
> > >
> > > On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <co...@apache.org>
> > wrote:
> > >
> > >> 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
> > >>
> > >
> > > Cos, no doubt this had come up before (after all, we did have very good
> > > mentors during the incubation process).
> > >
> > > Unfortunately, for tasks like this it is never a good time. I hope
> > someone
> > > in the community picks it up, or at least gets started on it.
> >
> >
>
Re: Move documentation from readme.io to GitHub pages
Posted by Pavel Tupitsyn <pt...@apache.org>.
Good news, Denis.
By the way, readme.io uses some kind of markdown dialect, and they have
"export" feature,
so it should be possible to move to some markdown-based system like Jekyll
without too much hassle.
On Thu, Feb 1, 2018 at 2:18 AM, Denis Magda <dm...@apache.org> wrote:
> Created a ticket. I think the time to move from readme.io <
> http://readme.io/> has come. It’s becoming too challenging to live with
> it:
> https://issues.apache.org/jira/browse/IGNITE-7595 <
> https://issues.apache.org/jira/browse/IGNITE-7595>
>
> —
> Denis
>
> > On Apr 13, 2017, at 8:25 AM, Dmitriy Setrakyan <ds...@apache.org>
> wrote:
> >
> > On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <co...@apache.org>
> wrote:
> >
> >> 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
> >>
> >
> > Cos, no doubt this had come up before (after all, we did have very good
> > mentors during the incubation process).
> >
> > Unfortunately, for tasks like this it is never a good time. I hope
> someone
> > in the community picks it up, or at least gets started on it.
>
>
Re: Move documentation from readme.io to GitHub pages
Posted by Denis Magda <dm...@apache.org>.
Created a ticket. I think the time to move from readme.io <http://readme.io/> has come. It’s becoming too challenging to live with it:
https://issues.apache.org/jira/browse/IGNITE-7595 <https://issues.apache.org/jira/browse/IGNITE-7595>
—
Denis
> On Apr 13, 2017, at 8:25 AM, Dmitriy Setrakyan <ds...@apache.org> wrote:
>
> On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <co...@apache.org> wrote:
>
>> 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
>>
>
> Cos, no doubt this had come up before (after all, we did have very good
> mentors during the incubation process).
>
> Unfortunately, for tasks like this it is never a good time. I hope someone
> in the community picks it up, or at least gets started on it.
Re: Move documentation from readme.io to GitHub pages
Posted by Dmitriy Setrakyan <ds...@apache.org>.
On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <co...@apache.org> wrote:
> 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
>
Cos, no doubt this had come up before (after all, we did have very good
mentors during the incubation process).
Unfortunately, for tasks like this it is never a good time. I hope someone
in the community picks it up, or at least gets started on it.
Re: Move documentation from readme.io to GitHub pages
Posted by Konstantin Boudnik <co...@apache.org>.
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
<ds...@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 <pt...@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 <dm...@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 <pt...@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?
>> >
>> >
>>
Re: Move documentation from readme.io to GitHub pages
Posted by Dmitriy Setrakyan <ds...@apache.org>.
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 <pt...@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 <dm...@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 <pt...@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?
> >
> >
>
Re: Move documentation from readme.io to GitHub pages
Posted by Pavel Tupitsyn <pt...@apache.org>.
> 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 <dm...@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 <pt...@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?
>
>
Re: Move documentation from readme.io to GitHub pages
Posted by Denis Magda <dm...@apache.org>.
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 <pt...@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?