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

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

[Daniel P. Berrangé]

Add a README file that tells people this is a jekyll based static
website, and shows people how to run jekyll for testing purposes.

Tested-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
 .gitignore  |  2 ++
 README      | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 _config.yml |  2 ++
 3 files changed, 59 insertions(+)
 create mode 100644 README

diff --git a/.gitignore b/.gitignore
index 29949d4..c744144 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,4 @@
 /_site
 /Gemfile.lock
+/vendor
+/.bundle
diff --git a/README b/README
new file mode 100644
index 0000000..2e591fe
--- /dev/null
+++ b/README
@@ -0,0 +1,55 @@
+QEMU Website
+============
+
+This repository provides content for the QEMU website.
+
+It uses the Jekyll site generator for turning the static content into
+a format which can then be directly hosted by a regular HTTP server
+such as Apache.
+
+
+Testing locally with Jekyll
+---------------------------
+
+When adding/changing content on this site, it is possible to run a
+local Jekyll service to test the result.
+
+QEMU requires a specific version of Jekyll (listedin Gemfile) which may
+not match that provided by your OS vendor. Thus as a one time step the
+required Jekyll software should be installed locally:
+
+* Install OS vendor ruby with development headers
+
+   # sudo dnf install ruby ruby-devel   (Fedora)
+   # sudo yum install ruby ruby-devel   (RHEL)
+   # sudo apt-get install ruby ruby-dev (Debian / Ubuntu)
+
+* Install OS vendor ruby gem bundler
+
+   # sudo dnf install rubygem-bundler  (Fedora)
+   # sudo yum install rubygem-bundler  (RHEL)
+   # sudo apt-get install bundler      (Debian / Ubuntu)
+
+* Install Jekyll and its dependencies
+
+   # bundle install --path vendor
+
+  NB this last command must be run from the qemu-web.git checkout
+  root directory.
+
+Jekyll is now installed into the 'vendor/' directory of the git checkout.
+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
+
+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 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
-- 
2.19.2

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

[Eric Blake]

On 11/29/18 4:46 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.
> 
> Tested-by: Eric Blake <eblake@redhat.com>
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>   .gitignore  |  2 ++
>   README      | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>   _config.yml |  2 ++
>   3 files changed, 59 insertions(+)
>   create mode 100644 README

> +Testing locally with Jekyll
> +---------------------------
> +
> +When adding/changing content on this site, it is possible to run a
> +local Jekyll service to test the result.
> +
> +QEMU requires a specific version of Jekyll (listedin Gemfile) which may

s/listedin/listed in/

> +++ b/_config.yml
> @@ -37,3 +37,5 @@ gems:
>   exclude:
>     - Gemfile
>     - Gemfile.lock
> +  - vendor/
> +  - README

Should .gitignore be in this list?  But that's pre-existing.

With the typo fix,
Reviewed-by: Eric Blake <eblake@redhat.com>

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

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

[Daniel P. Berrangé]

On Thu, Nov 29, 2018 at 07:34:56AM -0600, Eric Blake wrote:
> On 11/29/18 4:46 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.
> > 
> > Tested-by: Eric Blake <eblake@redhat.com>
> > Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> > ---
> >   .gitignore  |  2 ++
> >   README      | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++
> >   _config.yml |  2 ++
> >   3 files changed, 59 insertions(+)
> >   create mode 100644 README
> 
> > +Testing locally with Jekyll
> > +---------------------------
> > +
> > +When adding/changing content on this site, it is possible to run a
> > +local Jekyll service to test the result.
> > +
> > +QEMU requires a specific version of Jekyll (listedin Gemfile) which may
> 
> s/listedin/listed in/
> 
> > +++ b/_config.yml
> > @@ -37,3 +37,5 @@ gems:
> >   exclude:
> >     - Gemfile
> >     - Gemfile.lock
> > +  - vendor/
> > +  - README
> 
> Should .gitignore be in this list?  But that's pre-existing.

AFAICT, it excludes all dotfiles by default

> 
> With the typo fix,
> Reviewed-by: Eric Blake <eblake@redhat.com>
> 
> -- 
> Eric Blake, Principal Software Engineer
> Red Hat, Inc.           +1-919-301-3266
> Virtualization:  qemu.org | libvirt.org

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

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

[Thomas Huth]

On 2018-11-29 11:46, 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.
> 
> Tested-by: Eric Blake <eblake@redhat.com>
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>  .gitignore  |  2 ++
>  README      | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  _config.yml |  2 ++
>  3 files changed, 59 insertions(+)
>  create mode 100644 README

Thanks, applied (with the typo fixed).

 Thomas