ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Prachi Garg <pg...@gridgain.com>
Subject Re: Move documentation from readme.io to GitHub pages
Date Fri, 13 Apr 2018 17:10:32 GMT
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.


On Tue, Apr 10, 2018 at 4:52 PM, Denis Magda <dmagda@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 <dsetrakyan@apache.org>
> wrote:
>> On Wed, Mar 21, 2018 at 9:27 PM, Prachi Garg <pgarg@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!

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