Skip to contentSkip to conversation

Document how to test the site with jekyll locally

PATCH Superseded Daniel P. Berrangé 8 participants 14 messages Nov 28, 2018 – Dec 6, 2018

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Daniel P. Berrangé

author
#0 lore raw

PATCH 1/1 Document how to test the site with jekyll locally

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é <[email protected]>

---

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
README new file +53 -0
new file mode 100644
index 0000000..d06606a
@@ -0,0 +1,53 @@
+QEMU Webite
+===========
+
+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 which may not match that
+provided by your OS vendor. Thus as a one time step the Jekyll software
+must be installed locally as follows:
+
+* 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
+
+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 neccessary
+to restart jekyll after changing content, unless it shows signs of being
+confused / stale.
_config.yml +2 -0
index 0a0201c..576b0a5 100644
@@ -37,3 +37,5 @@ gems:
 exclude:
   - Gemfile
   - Gemfile.lock
+  - vendor/
+  - README
Signature · 1 line
2.19.2
#1 lore raw
Quoted 8 lines · 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.

Signed-off-by Daniel P. Berrangé <[email protected]>

---

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...

47 Paolo Bonzini <[email protected]>
44 Michael Roth <[email protected]>
13 Thomas Huth <[email protected]>
3 Eric Blake <[email protected]>
2 Daniel P. Berrange <[email protected]>
2 Jeff Cody <[email protected]>
1 Alex Bennée <[email protected]>
1 Daniel P. Berrangé <[email protected]>
1 Fam Zheng <[email protected]>
1 Rainer Müller <[email protected]>
1 Stefan Hajnoczi <[email protected]>
1 Yu Ning <[email protected]>

Anybody (especially non-RH people) disagrees with dual-license CC-BY-SA 4.0 and GPLv2+? (So that we can copy from blog posts to manuals)?

Paolo

author
#2 lore raw
Quoted 23 lines · Paolo Bonzini
Quoted 8 lines · 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.

Signed-off-by Daniel P. Berrangé <[email protected]>

---

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...

47 Paolo Bonzini <[email protected]>
44 Michael Roth <[email protected]>
13 Thomas Huth <[email protected]>
3 Eric Blake <[email protected]>
2 Daniel P. Berrange <[email protected]>
2 Jeff Cody <[email protected]>
1 Alex Bennée <[email protected]>
1 Daniel P. Berrangé <[email protected]>
1 Fam Zheng <[email protected]>
1 Rainer Müller <[email protected]>
1 Stefan Hajnoczi <[email protected]>
1 Yu Ning <[email protected]>

Quoted 2 lines

Anybody (especially non-RH people) disagrees with dual-license CC-BY-SA 4.0 and GPLv2+? (So that we can copy from blog posts to manuals)?

This dual license is exactly what I would have suggested too, as CC-BY-SA is common place for collaborative web content projects & formal docs efforts.

Regards,
Daniel

Signature · 3 lines
|: 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 :|
#3 lore raw
In reply to Paolo Bonzini
Quoted 7 lines · Paolo Bonzini
Quoted 6 lines · 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.

Signed-off-by Daniel P. Berrangé <[email protected]>

---

Quoted 8 lines
Quoted 2 lines

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...

3 Eric Blake <[email protected]>

Anybody (especially non-RH people) disagrees with dual-license CC-BY-SA 4.0 and GPLv2+? (So that we can copy from blog posts to manuals)?

For the avoidance of doubt, no disagreement with the proposal in regards to my edits (even if Red Hat can step in and make a broader statement on my behalf).

Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org
Acked-by
#4 lore raw
In reply to Paolo Bonzini

Fine with me.

Acked-by Alex Bennée <[email protected]>
Quoted 28 lines · On Wed, 28 Nov 2018, 16:44 Paolo Bonzini <[email protected] wrote:
Quoted 8 lines · 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.

Signed-off-by Daniel P. Berrangé <[email protected]>

---

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...

    47  Paolo Bonzini <[email protected]>
    44  Michael Roth <[email protected]>
    13  Thomas Huth <[email protected]>
     3  Eric Blake <[email protected]>
     2  Daniel P. Berrange <[email protected]>
     2  Jeff Cody <[email protected]>
     1  Alex Bennée <[email protected]>
     1  Daniel P. Berrangé <[email protected]>
     1  Fam Zheng <[email protected]>
     1  Rainer Müller <[email protected]>
     1  Stefan Hajnoczi <[email protected]>
     1  Yu Ning <[email protected]>

Anybody (especially non-RH people) disagrees with dual-license CC-BY-SA 4.0 and GPLv2+? (So that we can copy from blog posts to manuals)?

Paolo

#5 lore raw
In reply to Paolo Bonzini
Quoted 23 lines · Paolo Bonzini
Quoted 8 lines · 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.

Signed-off-by Daniel P. Berrangé <[email protected]>

---

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...

47 Paolo Bonzini <[email protected]>
44 Michael Roth <[email protected]>
13 Thomas Huth <[email protected]>
3 Eric Blake <[email protected]>
2 Daniel P. Berrange <[email protected]>
2 Jeff Cody <[email protected]>
1 Alex Bennée <[email protected]>
1 Daniel P. Berrangé <[email protected]>
1 Fam Zheng <[email protected]>
1 Rainer Müller <[email protected]>
1 Stefan Hajnoczi <[email protected]>
1 Yu Ning <[email protected]>

Quoted 2 lines

Anybody (especially non-RH people) disagrees with dual-license CC-BY-SA 4.0 and GPLv2+? (So that we can copy from blog posts to manuals)?

FWIW, dual-license is fine for me.

Thomas

#6 lore raw
In reply to Paolo Bonzini
Quoted 7 lines · Paolo Bonzini
Quoted 6 lines · 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.

Signed-off-by Daniel P. Berrangé <[email protected]>

---

Quoted 7 lines
Quoted 2 lines

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...

1 Rainer Müller <[email protected]>

Anybody (especially non-RH people) disagrees with dual-license CC-BY-SA 4.0 and GPLv2+? (So that we can copy from blog posts to manuals)?

No objections from my side.

Rainer

#7 lore raw
In reply to Paolo Bonzini
Quoted 10 lines

-----Original Message-----
From: Paolo Bonzini [mailto:[email protected]]
Sent: Thursday, November 29, 2018 0:44
To: Daniel P. Berrangé <[email protected]>; [email protected]
Cc: Thomas Huth <[email protected]>; [email protected]; [email protected]; Ning, Yu <[email protected]>; Eric Blake <[email protected]>; Stefan Hajnoczi <[email protected]>
Subject: Re: [qemu-web PATCH] Document how to test the site with jekyll locally

Quoted 4 lines

[...]

Anybody (especially non-RH people) disagrees with dual-license CC-BY-SA 4.0 and GPLv2+? (So that we can copy from blog posts to manuals)?

I agree with using this dual license.

Thanks,
Yu

author
#8 lore raw
In reply to Paolo Bonzini

Copying Michael Roth as the only remaining non-Red Hat contributor we still need approval from

Quoted 23 lines · Paolo Bonzini
Quoted 8 lines · 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.

Signed-off-by Daniel P. Berrangé <[email protected]>

---

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...

47 Paolo Bonzini <[email protected]>
44 Michael Roth <[email protected]>
13 Thomas Huth <[email protected]>
3 Eric Blake <[email protected]>
2 Daniel P. Berrange <[email protected]>
2 Jeff Cody <[email protected]>
1 Alex Bennée <[email protected]>
1 Daniel P. Berrangé <[email protected]>
1 Fam Zheng <[email protected]>
1 Rainer Müller <[email protected]>
1 Stefan Hajnoczi <[email protected]>
1 Yu Ning <[email protected]>

Quoted 4 lines

Anybody (especially non-RH people) disagrees with dual-license CC-BY-SA 4.0 and GPLv2+? (So that we can copy from blog posts to manuals)?

Paolo

Regards,
Daniel

Signature · 3 lines
|: 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 :|
#9 lore raw

Quoting Daniel P. Berrangé (2018-12-06 10:50:47)

Quoted 2 lines

Copying Michael Roth as the only remaining non-Red Hat contributor we still need approval from

No objections from my end.

Quoted 37 lines · Paolo Bonzini
Quoted 23 lines · Daniel P. Berrangé
Quoted 8 lines

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é <[email protected]>

---

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...

    47        Paolo Bonzini <[email protected]>
    44        Michael Roth <[email protected]>
    13        Thomas Huth <[email protected]>
     3        Eric Blake <[email protected]>
     2        Daniel P. Berrange <[email protected]>
     2        Jeff Cody <[email protected]>
     1        Alex Bennée <[email protected]>
     1        Daniel P. Berrangé <[email protected]>
     1        Fam Zheng <[email protected]>
     1        Rainer Müller <[email protected]>
     1        Stefan Hajnoczi <[email protected]>
     1        Yu Ning <[email protected]>
Quoted 4 lines

Anybody (especially non-RH people) disagrees with dual-license CC-BY-SA 4.0 and GPLv2+? (So that we can copy from blog posts to manuals)?

Paolo

Regards,
Daniel

Signature · 3 lines
|: 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 :|
#10 lore raw
In reply to Daniel P. Berrangé
Quoted 20 lines · 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.

Signed-off-by Daniel P. Berrangé <[email protected]>

---

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

README new file +0 -0
new file mode 100644
index 0000000..d06606a

README line 2

Quoted 2 lines
README new file +2 -0
@@ -0,0 +1,53 @@
+QEMU Webite
+===========

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

README line 36

Quoted 4 lines
README new file +4 -0
+* Install Jekyll and its dependencies
+
+   # bundle install --path vendor
+

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

What am I missing?

README line 37

Quoted 1 line
README new file +1 -0
+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).

README line 45

Quoted 8 lines
README new file +8 -0
+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?

README line 51

Quoted 6 lines
README new file +6 -0
+
+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/

Quoted 13 lines
README new file +2 -0
+to restart jekyll after changing content, unless it shows signs of being
+confused / stale.
_config.yml +2 -0
index 0a0201c..576b0a5 100644
@@ -37,3 +37,5 @@ gems:
  exclude:
    - Gemfile
    - Gemfile.lock
+  - vendor/
+  - README
Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org
author
#11 lore raw
Quoted 59 lines · Eric Blake
Quoted 20 lines · 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.

Signed-off-by Daniel P. Berrangé <[email protected]>

---

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

README new file +0 -0
new file mode 100644
index 0000000..d06606a

README line 2

Quoted 2 lines
README new file +2 -0
@@ -0,0 +1,53 @@
+QEMU Webite
+===========

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

README line 36

Quoted 4 lines
README new file +4 -0
+* Install Jekyll and its dependencies
+
+   # bundle install --path vendor
+

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

What am I missing?

README line 37

Quoted 1 line
README new file +1 -0
+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`
...
Quoted 3 lines

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).

Yes, 'bundle install' reads the versions from Gemfile, so it should get the right version that qemu-web wants. Thus I preferred not to duplicate the version in the docs too.

Quoted 23 lines

README line 45

Quoted 9 lines
README new file +8 -0
+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.
Quoted 1 line

Did I do things right?

Yes, but this error is what the addition in _config.yml.....

Quoted 10 lines

_config.yml gems: · line 41

Quoted 10 lines
_config.yml +2 -0
index 0a0201c..576b0a5 100644
@@ -37,3 +37,5 @@ gems:
  exclude:
    - Gemfile
    - Gemfile.lock
+  - vendor/
+  - README

...here is supposed to fix, so I'm puzzelled why you'd still get that error message

Regards,
Daniel

Signature · 3 lines
|: 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 :|
Tested-by
#12 lore raw
Quoted 22 lines · Daniel P. Berrangé
Quoted 22 lines

README line 45

Quoted 8 lines
README new file +8 -0
+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.
Quoted 3 lines
Quoted 1 line

Did I do things right?

Yes, but this error is what the addition in _config.yml.....

Ah, my fault for not actually applying the patch before trying the commands. With the patched _config.yml,...

Quoted 14 lines
Quoted 11 lines

_config.yml gems: · line 41

Quoted 11 lines
_config.yml +2 -0
index 0a0201c..576b0a5 100644
@@ -37,3 +37,5 @@ gems:
   exclude:
     - Gemfile
     - Gemfile.lock
+  - vendor/
+  - README

...here is supposed to fix, so I'm puzzelled why you'd still get that error message

...I have a live local server.

Tested-by Eric Blake <[email protected]>
Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org
#13 lore raw
Quoted 4 lines · Eric Blake

...I have a live local server.

Tested-by Eric Blake <[email protected]>

I'd also update .gitignore to exclude .bundle/ and vendor/, since those now show up as untracked after my testing.

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