Skip to content
The home of the Chisel3 website
Makefile Scala Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
chisel-testers @ e93ed62
chisel3 @ d1a6126
diagrammer @ 1a63226
docs/src/main
firrtl @ f738fbe
project
scripts
treadle @ daef09e
.gitignore
.gitmodules
.travis.yml
LICENSE
Makefile
README.md
build.sbt
travis-deploy-key.enc

README.md

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 both sbt and jekyll.

Building 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
You can’t perform that action at this time.