You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ignite.apache.org by Prachi Garg <pg...@gridgain.com> on 2018/03/20 23:38:10 UTC
Re: Move documentation from readme.io to GitHub pages
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 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/
> > >>
> >
> >
>