Chisel-Lang Website

This repository provides the meta-website for Chisel, FIRRTL, and associated projects.

Contributing

We accept modifications to the website via Pull Requests. All Pull Requests must both (1) be reviewed before they can be merged and (2) must pass Travis CI regression testing. After a Pull Request is merged, a second Travis CI build will run on the master branch that will build and update the website.

Requirements

To build the website you need:

• sbt
• jekyll
• gmake - tested with version 4.2.1

Installing jekyll

sudo apt-get install jekyll
gem install jekyll-redirect-from

Building the Website

tl;dr:

# Clone this git repository
git clone [email protected]:freechipsproject/www.chisel-lang.org

# Change into the directory where the clone lives
cd www.chisel-lang.org

# Checkout submodules (the README.md of submodules are used to populate the site)
git submodule update --init --recursive

# (Optionally:) Download a copy of the API documentation (this speeds up the build if building with API docs)
wget https://github.com/freechipsproject/www.chisel-lang.org/releases/latest/download/build.tgz -O - | tar -xz

# (Optionally:) Set NO_API environment variable to exclude building the API docs.
#   This makes building the website *much* faster but leaves the API docs as dead links in the locally served website.
export NO_API=true

# Build the website
make

# Serve the website
make serve

# In a web browser navigate to localhost:4000 to preview the website

The build process uses a Makefile to orchestrate building the website. This Makefile does a number of actions:

1. Determines Contributors

There have been a lot of contributors to Chisel, FIRRTL and associated projects. As a small token of thanks, anyone who was contributed to these projects is listed on the website's community tab.

The website uses an sbt task that uses github4s to query GitHub for a list of contributors.

You can run this manually with:

make docs/src/main/tut/contributors.md

2. Builds Scaladoc for Project Versions

The website includes Scaladoc for both the current and legacy versions of Chisel, FIRRTL, and related projects. The specific versions built are defined in the Makefile. Each version corresponds to an associated git tag for that project.

Each $(project)--$(tag) tuple is cloned into $(buildDir)/subprojects/$(project)/$(tag). Documentation is built inside that project using either sbt doc or sbt unidoc (depending on the project). The built Scaladoc is then copied into $(buildDir)/api/$(project)/$(tag). By copying the documentation out of the subproject/ directory, only the Scaladoc can be cached (either locally or on Travis) preventing the build process from having to keep around a clone of every $(project)--$(tag) tuple.

The Scaladoc is then copied into docs/target/site/api while removing the leading v from the directory name.

The actual linking on the website is handled by docs/src/main/resources/microsite/data/menu.yml.

Phony build targets, used by Travis CI, to build only specific documentation (into $(buildDir)/api/) can be used, e.g., to build only Chisel documentation:

make apis-chisel

3. Builds SNAPSHOT Scaladoc

In addition to documentation of tagged versions, the website also provides a link to a SNAPSHOT release. This can be any tag that the Makefile defines and could be any of:

• A full version
• A SNAPSHOT release
• A release candidate

The Makefile will then (build that tagged version if needed and) add a symlink called latest that points at the requested documentation. Each project then has a SNAPSHOT link in its documentation that points at this version.

4. Builds the Website

The actual website is assembled using sbt-microsite. You can build this manually with:

sbt docs/makeMicrosite

Building and Testing Everything

To build the complete website use (and consider using the -j option with an appropriate number of parallel tasks to speed it up):

make

Initially building the website takes a long time (~45 minutes) due to the need to build Scaladoc documentation for versions. However, this process is embarrassingly parallel and you only need to do it once. All legacy/snapshot documentation will be cached in $(buildDir)/api/. Due to this caching, building the website after changes takes only a couple of minutes (the website is big...).

After making modifications to the website, you can host it locally with (so long as you have installed jekyll):

make serve

Navigate to 127.0.0.1:4000 to view your modifications to the website.

Cleaning Things Up

There are two targets for cleaning the build:

• To clean the website build use make clean (this will not remove built Scaladoc documentation)
• To clean everything (including cached Scaladoc) use make mrproper