Mailing-List: contact dev-help@brooklyn.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@brooklyn.incubator.apache.org
Received-SPF: pass (athena.apache.org: domain of david.toy@cloudsoftcorp.com
 designates 209.85.216.169 as permitted sender)
MIME-Version: 1.0
Date: Tue, 20 May 2014 13:32:30 +0100
Message-ID: 
 <CAPW-WYRTL-JFBTNFCBQ61-AF3MAx4v3EzzQ51rUeMoNinBcWSg@mail.gmail.com>
Subject: Re: Problems building the docs
From: David Toy <david.toy@cloudsoftcorp.com>
To: dev@brooklyn.incubator.apache.org
Content-Type: multipart/alternative; boundary=001a11c13692d37f1604f9d41281

--001a11c13692d37f1604f9d41281
Content-Type: text/plain; charset=UTF-8

Richard,

Martin's advice is still good. The Jekyll downgrade was a temporary
solution that stuck. If required, old and new Jekyll can be installed
without conflict. See this gist [1].

It appears that you have already started work on upgrading Brooklyn to use
the newer versions of Jekyll. Good, but this may need to be tackled as a
larger incubation process task.

Currently the site url, used for specifying front page (/) or
versionedcontent (/v/0.7.0-M1/), is passed as an argument to build.sh,
which passes
this as a command line argument to Jekyll. New version of Jekyll do not
support the command line parameters, so build.sh will have to modify
Jekyll's config file on the fly.

The json problem[2] is the result of a 'missing' file. The path in line 5
looks wrong; wasn't expecting double dot sibling traversal. If you didn't
change any of the toc.jsons, then I suspect that the url parameter
(site_url?) is
missing from your new yaml config, or that the newer version of Jekyll are
handling paths differently.

otoh: Jekyll 0.11.2 works for Martin and I.  :)

hth,
David

1. https://gist.github.com/jdtoy/9529932
2. http://pastie.org/private/uvdd6nel8fvdbcxomse4bq#5-7,9


Hi Richard,
> David Toy sent me this a while ago when I was working on the docs. It was
> sent last October, so I don't know how current it is...:
> Hi Martin,
> Jekyll has been updated and changed how parameters are specified, in a non
> backwards compatible way.
> // Aside: Some significant tweaking will be required to update how we build
> Brooklyn docs to be compatible with the current version of Jekyll.
> Here is a temporary workaround to downgrade Jekyll:
> *Remove the new version of Jekyll:*
> % sudo gem uninstall jekyll
> *Add an older version [1]:*
> % wget --no-check-certificate https://github.com/mojombo/jekyll
> /archive/v0.11.2.tar.gz > jekyll-0.11.2.tar.gz
> % tar -zxf  jekyll-0.11.2.tar.gz
> % cd jekyll-0.11.2.tar.gz
> % gem build jekyll.gemspec
> % sudo gem install jekyll-0.11.2.gem
> 1. I'm using 0.11.2 at the moment, but I see that it is now ancient, and
> there has been plenty of activity since it was released. A dive into
> https://github.com/mojombo/jekyll/releases will show when the url
> parameters were changed. (perhaps on transition to version 1?)
> Thanks,
> David
>
> On 19 May 2014 17:40, Richard Downer <richard@apache.org> wrote:
> > Hi,
> >
> > I'm having trouble building docs at the moment. At the root is that
> > Jekyll has moved on a few versions and the Brooklyn docs scripts are
> > no longer compatible - so when I start from a clean Ruby environment
> > and follow the instructions at
> > https://brooklyncentral.github.io/dev/tips/update-docs.html (which
> > don't say what component versions they use), when I invoke
> > _scripts/build.sh I got errors:
> >
> >        Deprecation: Jekyll now uses subcommands instead of just
> > switches. Run `jekyll help' to find out more.
> >        Deprecation: The 'pygments'settings has been removed in favour
> > of 'highlighter'.
> > /Users/richard/.rvm/gems/ruby-2.1.0@llp-rpi
> > /gems/mercenary-0.3.3/lib/mercenary/program.rb:30:in
> > `go': invalid option: --pygments (OptionParser::InvalidOption)
> >
> > This is no problem - a couple of tweaks to _config.yml and
> > _scripts/build.sh fixes that. (See
> > https://gist.github.com/richardcloudsoft/cbd0682522b3ed815122)
> >
> > But it results in a much longer error message about malformed JSON,
> > which is too long to post here - see:
> > http://pastie.org/private/uvdd6nel8fvdbcxomse4bq
> >
> > Any ideas what is going wrong here?
> >
> > Thanks
> > Richard.
> >

--001a11c13692d37f1604f9d41281--