ev3dev / ev3dev.github.io

pretty web page for ev3dev

Pretty website for ev3dev

This is the source repository for the web page at http://www.ev3dev.org. If you want to learn more about ev3dev in general, visit the site or check out our GitHub repo.

Feel free to fork and make a pull request! If you're looking for ways to contribute to our website, check out issues tagged "help wanted"; there are often tasks there which are well-suited to new contributors.

Previewing Locally

You can view your changes locally by installing Jekyll.

Installing Jekyll in Ubuntu 16.04

Install Ruby via apt-get

sudo apt-get install git ruby ruby-dev zlib1g-dev nodejs
sudo gem install bundler

Install Ruby via RVM (Ruby Version Manager)

If you use ruby for other things and don't want to mess up you system ruby installation, you can install ruby via rvm instead. Note that you must do the 'source' line when you open a new xterm or add it to ~/.bashrc.

gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
\curl -sSL https://get.rvm.io | bash -s stable --ruby
source ~/.rvm/scripts/rvm

You will still need to run the following too...

sudo apt-get install git zlib1g-dev nodejs
sudo gem install bundler

Check Out Code and Run Jekyll

git clone [email protected]:<user>/ev3dev.github.io
cd ev3dev.github.io
bundle install
bundle exec jekyll serve --safe --incremental &
www-browser http://localhost:4000 &
# work, work, work

Installing Jekyll on Windows

First, follow the instructions in step 1 here: "Installing Ruby and the Ruby DevKit."

Then run:

gem install bundler
git clone https://github.com/<user>/ev3dev.github.io
cd ev3dev.github.io
bundle install
bundle exec jekyll serve --safe --incremental

Now you should be able to visit your page at: http://localhost:4000. It should auto-update when you change the source files, so all you have to do is refresh your browser.

Previewing Your Changes Online

After you have previewed your changes locally, you can use a special Ruby script to publish your changes using the gh-pages branch of your fork of ev3dev.github.io.

If you have SSH setup for your GitHub account, simply run ./publish.rb <gh-user> --ssh where <gh-user> is your actual GitHub user name. If you do not have SSH set up, use ./publish.rb <gh-user>. This will copy the contents of _site, fix it up a bit and push it to your fork on GitHub. You can view the results at http://<gh-user>.github.io/ev3dev.github.io.

ev3dev.github.io's Issues

Emphasize next steps in Getting Started

Make the links to the "Libraries" page from "Getting Started" more obvious and natural as the next step.

This could be taken further by having the "introductory pages" display a "Next step" button at the bottom of the page. This would help with the flow of that series.

From ev3dev/ev3dev#734.

Publish script adjusting YouTube video URLs

I'm getting 404s on my preview site because the YouTube embed iframe is referencing /ev3dev.github.io//www.youtube.com/embed/tg4IwxdkICM?rel=0.

Create page on installing new software

Link to it from Getting Started.

From ev3dev/ev3dev#734

Headers are cut off on mobile (and very close to the top on the desktop)

Headers need some extra top margin or padding so that they (along with any content floating right in the same horizontal row) don't go under the header.

Publish script should disable Jekyll

I believe there's a system for disabling Jekyll (something along the lines of adding a .nojekyll file). The publish script should do that so that GitHub doesn't try to build the static HTML.

Figure out a way to keep old versions of docs for historical reference

It would be great if we could keep versions of docs for old kernels available so that people can reference information for previous releases. I'm imagining some form of a page_version property that generates a dropdown or other control on all versions of the page. We'd need to make a copy of a page and change its name to archive it.

Add a separate page which explains ev3dev

From ev3dev/ev3dev#734.

"http://lab.open-roberta.org/" is throwing errors and failing the CI build

Currently, CI builds fail with errors about not being able to access http://lab.open-roberta.org/. I tried it in multiple browsers locally and I can't access that URL either (it times out after a few minutes and displays a server error page). I'm pretty sure that this worked before, but it looks like they are having some severe server troubles.

For reference, this is the page that it brings me to after the timeout period:

Also pinging @ensonic so he's aware, as this is generally his domain.

Revise nav links to prioritize important information

• Home
• Get started
• Documentation (clicking this should lead to the docs landing page)
  • Tutorials
  • Libraries
  • Low-level driver access
  • More... (also links to landing page)
    • the landing page needs to have links to everything that is in the Documentation nav menu, at a minimum.
• Get help
• News
• Community
  • Project showcase
  • Contribute
  • Share

From ev3dev/ev3dev#734

Projects page grid is horribly misaligned

Due to some shortcuts that were taken when creating the projects page (not naming names 😉), the variable length of project descriptions has caused the grid to become very badly aligned.

Involved page: http://www.ev3dev.org/projects/

JS should only be loaded after all other content has been loaded

The JS links should be at the end of the body so that the JavaScript is loaded and executed after the browser is already showing styled content.

github-cards need tweaking for horizontal layout

Example from http://www.ev3dev.org/docs/tutorials/setting-up-an-nfs-file-share/

Add landing page for ev3dev drivers/other technical topics

The motor/sensor classes should be easy to access; everything else should be demoted.

From ev3dev/ev3dev#734

Docker image used in docker tutorial fails to run

Following the Docker tutorial, attempting to run the Docker image results in the following error:

$ docker run --rm -it -v /Users/dgoodman/Documents/Projects/ev3/:/home/compiler/example ev3cc
standard_init_linux.go:175: exec user process caused "exec format error"

Docker version 1.12.0, build 8eab29e on OS X 10.11.6

Google is mis-capitalizing "ev3dev"

Google's results for some ev3dev-related searches are using titles that end with "Ev3Dev". I'm not sure where it is getting this string from, but I'm worried that it might be guessing the proper caps (first letter of each word, delimited by non-letters maybe?). This might explain why we've seen so many people open issues using this capitalization scheme.

Tabs for hardware platform on getting started page

The getting started page is getting somewhat cluttered with buttons and exceptions for the various hardware platforms.

What about using tabs for EV3/Raspberry Pi/Beablegone? (Like you do for Mac/Ubuntu/Windows on the networking page).

It adds some slight overhead for the maintainers, but it's only the getting started page.

Choose new image for "jumbotron" section on home page

Now that the splash screen has been removed / shrunk, there isn't any relevance to the boot splash image that we are showing on the home page anymore. It would be nice to have some more relevant image, or maybe even something that covered the whole width as a background. The existing image was more grandfathered in from the previous site design than chosen explicitly.

Search algorithm is very basic and makes search difficult to use

The search algorithm just looks for the keywords as-is in the titles of pages to find results. It should instead look for partial matches and assign each result some sort of point value that can then be used to sort the results. This also means that we probably want to remove the section headings from the results view.

Search box hasn't been adapted for mobile

We currently just hide the search box on smaller screens. We should instead make it usable on a touchscreen.

Add link to our GitHub organization

From ev3dev/ev3dev#734.

Add a networking landing page and make sure users go through it

From ev3dev/ev3dev#734.

Line wrapping

When we are writing markdown for the website, what line length should be wrap at?

I would vote for 120 or 130 characters, but I want to reach a decision and standardize.

Promote the support page/content

We should try to mention the support page as much as possible, and make it as inviting as possible.

From ev3dev/ev3dev#734.

Limit item count in news rss/atom feed

I'm not sure what triggered it, but my rss reader decided that all of our news articles were new, which was 41. Most rss feeds are limited to the 10 most recent articles. This would also be nice for new subscribers.

Simplify new project creation

In the project creation tutorial, we currently instruct the user to open the example post from GitHub, copy the content, and then paste it into a new file. It would be easier if we simply gave the content to them on the page and had them copy it from there.

I'd be interested to see if there's something similar to the built-in Gist functionality that would let us host a nicely-formatted code block that would pull from the existing file so we don't have to paste the example content into the tutorial. that's something to look into.

P.S. I noticed some other problems with the project tutorial that I'll be fixing in a PR soon.

Download section

It would be really nice to have a downloads page with a link to the nightly builds (which are hosted here).

The latest build for the ev3 was almost 10 months ago...

Links to Apple documentation from NFS tutorial are now broken

The CI server is seeing a few broken links to Apple docs from the NFS tutorial. My guess is that these pages were moved around on Apple's side, because I can't access them from my browser either.

Relevant log section from build job:

- ./docs/tutorials/setting-up-an-nfs-file-share/index.html
  *  External link https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man8/nfsd.8.html failed: 404 No error
  *  External link https://developer.apple.com/library/mac/documentation/Darwin/Reference/Manpages/man5/exports.5.html failed: 404 No error
  *  External link https://developer.apple.com/library/mac/documentation/Darwin/Reference/Manpages/man8/showmount.8.html failed: 404 No error

A search on their site returns links to the right pages, but those links are the same as ours and hence broken. Maybe this is temporary (an accident)?

Pinging @antonvh -- do you know what these links should be pointing to now?

Project pages showing unrendered markdown

Something we've done has broken the formatting on the Treev3 project page as well as a few others. Some of the Markdown is rendering in HTML view as raw text instead of being converted to HTML tags.

avahi-daemon: invalid response packet from host

I'm able to get ev3dev loaded on an ev3 without any problem. However, after the ev3 boots up, about 50% of the cpu is taken for system tasks.

top - 18:50:21 up 22 min,  1 user,  load average: 1.31, 1.20, 0.97
Tasks:  59 total,   1 running,  58 sleeping,   0 stopped,   0 zombie
%Cpu(s):  0.9 us, 56.3 sy,  0.0 ni, 41.9 id,  0.7 wa,  0.0 hi,  0.2 si,  0.0 st
KiB Mem:     59436 total,    57632 used,     1804 free,     5068 buffers
KiB Swap:    98300 total,     1216 used,    97084 free.    31468 cached Mem

I checked journalctl and it shows that the avahi-daemon is having some errors.

Mar 07 18:51:00 ev3dev avahi-daemon[268]: Invalid response packet from host 10.139.101.26.
Mar 07 18:51:01 ev3dev avahi-daemon[268]: Invalid response packet from host 10.139.101.26.
Mar 07 18:51:02 ev3dev avahi-daemon[268]: Invalid response packet from host 10.139.101.26.
Mar 07 18:51:02 ev3dev avahi-daemon[268]: Invalid response packet from host 10.139.101.26.

After googling this error, it appears to be a known bug. The bug reports say it has been fixed. Though it appears that the version in ev3dev doesn't have the patch. Any suggestions for how to proceed?

Make search auto-select top choice on "enter"

(Solved) Installing bundler on Ubuntu 16.04: ffi and nokogiri

I had two issues performing the step

sudo gem install bundler

On Ubuntu 16.04. Apparently, ffi and nokogiri failed to build.

To fix it, [source 1, source 2] run:

sudo apt-get install ruby-dev
sudo apt-get install zlib1g-dev

And then installing bundler again completed successfully. Perhaps these two packages could be added to the apt-get instructions already in the readme. Also, the "2.0" packages "ruby2.0 ruby2.0-dev" don't seem to exist in 16.04.

For reference, the error messages are posted below.

Installing ffi 1.9.14 with native extensions

Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

    current directory: /tmp/bundler20160905-5727-1ga529ffi-1.9.14/gems/ffi-1.9.14/ext/ffi_c
/usr/bin/ruby2.3 -r ./siteconf20160905-5727-mho9w6.rb extconf.rb
mkmf.rb can't find header files for ruby at /usr/lib/ruby/include/ruby.h

extconf failed, exit code 1

Gem files will remain installed in /tmp/bundler20160905-5727-1ga529ffi-1.9.14/gems/ffi-1.9.14 for inspection.
Results logged to /tmp/bundler20160905-5727-1ga529ffi-1.9.14/extensions/x86_64-linux/2.3.0/ffi-1.9.14/gem_make.out

(...)

An error occurred while installing ffi (1.9.14), and Bundler cannot continue.
Make sure that `gem install ffi -v '1.9.14'` succeeds before bundling.

Installing nokogiri 1.6.8 with native extensions

Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

    current directory: /tmp/bundler20160905-11974-ln6hq2nokogiri-1.6.8/gems/nokogiri-1.6.8/ext/nokogiri
/usr/bin/ruby2.3 -r ./siteconf20160905-11974-klmref.rb extconf.rb
Using pkg-config version 1.1.7
checking if the C compiler accepts ... yes
Building nokogiri using packaged libraries.
Using mini_portile version 2.1.0
checking for gzdopen() in -lz... no
zlib is missing; necessary for building libxml2
*** extconf.rb failed ***
Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers.  Check the mkmf.log file for more details.  You may
need configuration options.

Provided configuration options:
    --with-opt-dir
    --without-opt-dir
    --with-opt-include
    --without-opt-include=${opt-dir}/include
    --with-opt-lib
    --without-opt-lib=${opt-dir}/lib
    --with-make-prog
    --without-make-prog
    --srcdir=.
    --curdir
    --ruby=/usr/bin/$(RUBY_BASE_NAME)2.3
    --help
    --clean
    --use-system-libraries
    --enable-static
    --disable-static
    --with-zlib-dir
    --without-zlib-dir
    --with-zlib-include
    --without-zlib-include=${zlib-dir}/include
    --with-zlib-lib
    --without-zlib-lib=${zlib-dir}/lib
    --enable-cross-build
    --disable-cross-build

To see why this extension failed to compile, please check the mkmf.log which can be found here:

  /tmp/bundler20160905-11974-ln6hq2nokogiri-1.6.8/extensions/x86_64-linux/2.3.0/nokogiri-1.6.8/mkmf.log

extconf failed, exit code 1

Gem files will remain installed in /tmp/bundler20160905-11974-ln6hq2nokogiri-1.6.8/gems/nokogiri-1.6.8 for inspection.
Results logged to /tmp/bundler20160905-11974-ln6hq2nokogiri-1.6.8/extensions/x86_64-linux/2.3.0/nokogiri-1.6.8/gem_make.out

Remove erroneous periods in page titles

It looks like there are needless periods at the end of some page titles, e.g. Writing an SD Card Image Using Command Line Tools on OS X.

author cards messed up

Example: http://www.ev3dev.org/news/2016/01/25/evb-ev3dev-jessie-2016-01-25-release/

Firefox 45 on Ubuntu 16.04

Remove "calling it a day" section

I think this breaks the flow of the Getting Started guide. This content is valuable, so we may want to break it out into its own page, but the last step in the guide should lead into something about writing code without any barriers in between.

From ev3dev/ev3dev#734.

Update logic to use where_exp

GH Pages will upgrade to Jekyll 3.2 on the 23rd, meaning that the where_exp filter will be available. We should use it; it would greatly simplify some of our loops.

Switch website to using Sass instead of plain CSS

Jekyll natively supports Sass. Instead of using custom-compiled Bootstrap and CSS additions, we should see if we can get Jekyll to build Bootstrap for us. Then our custom theme modifications won't need to be manually compiled, and we can stop using CSS hacks to modify Bootstrap code.

---

I have a successful local test of building Bootstrap + Bootswatch in a Jekyll site. At some point soon I'll try to get our custom adaptations extracted from our site, re-written as Sass, and then put in the right place so that Bootstrap builds with our custom stuff.

From my tests, it looks like this adds around a second of build time; this isn't optimal, but hopefully with Jekyll 3.0's new profiling tool we can speed up our site build anyway.

Latest failure.

Don't know what this means and don't feel like looking into it at the moment, so I'll leave it here for investigation later...

- ./news/index.html
  *  Tag code... invalid (line 201)
  *  error parsing attribute name (line 201)
htmlproofer 3.0.5 | Error:  HTML-Proofer found 2 failures!

Add descriptions of individual tutorial categories and page as a whole

From ev3dev/ev3dev#734

ev3dev-lang-java links broken

@jabrena, it looks like you moved the ev3dev-lang-java site. Can you please fix the links in https://github.com/ev3dev/ev3dev.github.io/blob/master/news/_posts/2016-02-07-evb-ev3dev-lang-java-release-0.2.0.md?

Misplaced DOCTYPE declaration

Latests CI tests are showing lots of Misplaced DOCTYPE declaration. I think at least two of these pages are redirects created by the jekyll-redirect-from plugin, so something may be broken with that plugin.

- ./contributing/index.html
  *  Misplaced DOCTYPE declaration (line 175)
- ./docs/kernel-hackers-notebook/ev3-adc/index.html
  *  External link http://www.lm-sensors.org/ failed: got a time out (response code 0)
- ./docs/tutorials/writing-sd-card-image-mac-command-line/index.html
  *  Misplaced DOCTYPE declaration (line 175)
- ./issues/index.html
  *  Misplaced DOCTYPE declaration (line 175)
- ./news/2015/07/08/Kernel-Release-v3.16.7-ckt11-5-ev3dev-ev3.html
  *  Misplaced DOCTYPE declaration (line 175)
- ./news/2015/07/08/ev3-ev3dev-jessie-2015-07-08-release/index.html
  *  internally linking to /news/2015/07/08/Kernel-Release-v3.16.7-ckt11-5-ev3dev-ev3, which does not exist (line 195)

Use tiling library instead of Bootstrap grid on index pages

The "projects" page is having issues with scaling and flow because we are using hard-coded rows and Bootstrap classes. We should be using one of the existing tiling libraries that works with Bootstrap.

glyphicons broken when previewing site with publish.rb

For some reason the alert icons, which use glyphicon font, are broken when I publish a page for preview.

Example: http://dlech.github.io/ev3dev.github.io/docs/getting-started/

Update Getting Started to link to new landing pages (e.g. networking)

Update "tutorials" page to use masonry

Now that the mechanics of masonry have already been figured out for the "projects" page, migrating the "tutorials" page shouldn't be very difficult.

Odd logo background size in Firefox

I just noticed an odd behavior of the darkened logo background on Firefox (both Ubuntu and Windows):

The background in the upper-left corner is 90+ pixels instead of the expected 62. @dlech do you see the same? Tested in FF 37 and 44.

Add more landing pages for documentation categories

Initial ideas:

• "Connecting to the internet/a network"
• "Installing software"
• "Writing code using a library"
• "Running code"
• "Interfacing with ev3dev drivers directly"

These should be linked to from the documentation landing page, at a minimum.

From ev3dev/ev3dev#734.

link verification does not always work for https sites on travis

Searching google for html-proofer travis ssl shows we aren't the only ones that are having issues.

The latest is https://www.hiawatha-webserver.org/. We are also already ignoring https://warmcat.com because of ssl issues.

These work locally, but not on travis for whatever reason.

Get publish script working on Windows

Currently, the publish.rb script doesn't work on Windows. As far as I can tell, this is just because of the eval()-ed grep call. If we can find an alternative way in native Ruby, that would make it much easier to publish from Windows

Add icon to edit links

This is more of a note-to-self than anything else. It would be nice to have a pencil icon on the "edit on GitHub" links.

Getting started guide should highlight libraries instead of drivers

At this point, I think that docs for the underlying drivers are less useful than links to libraries. So, I'd say that the libraries should be front-and-center in that section.