Re: [Qemu-devel] [qemu-web PATCH] Document how to test the site with jekyll locally

[Eric Blake]

On 11/28/18 9:35 AM, Daniel P. Berrangé wrote:
> Add a README file that tells people this is a jekyll based static
> website, and shows people how to run jekyll for testing purposes.
>
> Signed-off-by: Daniel P. Berrangé <address@hidden>
> ---
>
> NB, we should really mention a license in the README too, but I don't
> see info about what license we consider qemu-web to be covered by...
>
>   README      | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>   _config.yml |  2 ++
>   2 files changed, 55 insertions(+)
>   create mode 100644 README
>
> diff --git a/README b/README
> new file mode 100644
> index 0000000..d06606a
> --- /dev/null
> +++ b/README
> @@ -0,0 +1,53 @@
> +QEMU Webite
> +===========

s/Webite/Website/ (and the corresponding = line lengthening)


> +* Install Jekyll and its dependencies
> +
> +   # bundle install --path vendor
> +

$ pwd
/home/eblake
$ bundle install --path vendor
Could not locate Gemfile

What am I missing?

> +Jekyll is now installed into the 'vendor/' directory of the git checkout.

Oh - this step must be run within the top-level directory of the 
qemu-web.git checkout (which might be obvious for someone reading the 
README from a fresh qemu-web git checkout, but wasn't for me while 
reviewing the patch).  So I repeated the command in the right directory, 
and it appears to work:

$ bundle install --path vendor
Fetching gem metadata from https://rubygems.org/..............
Fetching gem metadata from https://rubygems.org/..
Resolving dependencies...
Fetching public_suffix 2.0.5
...
Installing jekyll 3.3.0
...
Bundle complete! 9 Gemfile dependencies, 25 gems now installed.
Bundled gems are installed into `./vendor`
...

but I don't know if it is the same version of Jekyll that the 
documentation wanted ("QEMU requires a specific version of Jekyll which 
may not match that provided by your OS vendor" doesn't actually say 
WHICH specific version).

> +Note the 'vendor/' path has been explicitly excluded from the web content
> +in _config.yml, so don't try to use a different path within the git
> +checkout.
> +
> +
> +To test the site launch jeykll
> +
> +  # bundle exec jekyll serve

$ bundle exec jekyll serve
Configuration file: /home/eblake/qemu-web/_config.yml
Configuration file: /home/eblake/qemu-web/_config.yml
            Source: /home/eblake/qemu-web
       Destination: /home/eblake/qemu-web/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
             ERROR: YOUR SITE COULD NOT BE BUILT:
                    ------------------------------------
                    Invalid date '<%= Time.now.strftime('%Y-%m-%d 
%H:%M:%S %z') %>': Document 
'vendor/ruby/2.5.0/gems/jekyll-3.3.0/lib/site_template/_posts/0000-00-00-welcome-to-jekyll.markdown.erb' 
does not have a valid date in the YAML front matter.

Did I do things right?

> +
> +Now simply point a local web browser to http://127.0.0.1:4000 to browse
> +the generated site.
> +
> +Jekyll will usually automatically detect changes to files in the git
> +checkout and regenerate the site. It is thus not normally neccessary

s/neccessary/necessary/

> +to restart jekyll after changing content, unless it shows signs of being
> +confused / stale.
> diff --git a/_config.yml b/_config.yml
> index 0a0201c..576b0a5 100644
> --- a/_config.yml
> +++ b/_config.yml
> @@ -37,3 +37,5 @@ gems:
>   exclude:
>     - Gemfile
>     - Gemfile.lock
> +  - vendor/
> +  - README

--
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org