Skip to content

optimsoc/optimsoc-web

Repository files navigation

OpTiMSoC Web Site

The OpTiMSoC web site consists of two parts:

  1. The site itself, written mostly in Markdown and transformed into static HTML Jekyll (as provided by Github pages). This also includes the blog.
  2. The documentation, which is generated by Sphinx from rST sources. The API documentation is also converted into rST and then transformed into HTML and PDF using Sphinx.

Required Software

  • libffi (development packages)
  • Python 3
  • Python 3 venv
  • Ruby 2.1 (or higher)
  • Bundler
  • Doxygen

When using Ubuntu, install all build dependencies with this command:

sudo apt-get install libffi-dev python3 python3-venv python3-wheel ruby ruby-bundler doxygen

In addition, Jekyll needs to be installed through bundler:

bundle install --path=vendor/bundle

Build documentation

To create HTML (and optionally, PDF) documents from the documentation you can use the build-docs.sh script. It runs all necessary tools, such as Breathe and Sphinx and stores the results in the docs/ folder.

./build-docs.sh

To use another copy of the optimsoc source repository (like a local one):

./build-docs.sh file://$HOME/src/optimsoc/docs

Build the web site

The web site contains content written in Markdown together with HTML documents (such as the documentation). All those content documents need to be stitched together, put into a common layout template and prepared for being put on a web server. For this job we use Jekyll. Run the following command to build the site:

bundle exec jekyll build

This command will stitch the site together and place it as static HTML files inside the _site folder. You could take this folder and store it on a web server.

For the OpTiMSoC site, it's sufficient to push changes to the git repository. The changes will then be picked up and automatically published on the web server.

View the site

To test the site on your local machine run

bundle exec jekyll serve -w

And then point your browser to http://localhost:4000 to view the page.

Stock photos

blocks on front page