Move documentation from readme.io to GitHub pages

[Prachi Garg]

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 <[hidden email]>
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.
>

[dsetrakyan]

On Wed, Mar 21, 2018 at 9:27 PM, Prachi Garg <[hidden email]> 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!

[Denis Magda]

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 <[hidden email]>
wrote:

> On Wed, Mar 21, 2018 at 9:27 PM, Prachi Garg <[hidden email]> 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!
>

[Prachi Garg]

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 <[hidden email]> 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 <[hidden email]>
> wrote:
>
>> On Wed, Mar 21, 2018 at 9:27 PM, Prachi Garg <[hidden email]> 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!
>>
>
>