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.
To build the website you need both
Building the Website
The build process uses a
Makefile to orchestrate building the website.
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:
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
Each version corresponds to an associated git tag for that project.
$(tag) tuple is cloned into
Documentation is built inside that project using either
sbt doc or
sbt unidoc (depending on the project).
The built Scaladoc is then copied into
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
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
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:
3. Builds SNAPSHOT Scaladoc
In addition to documentation of tagged versions, the website also provides a link to a
This can be any tag that the
Makefile defines and could be any of:
- A full version
- A release candidate
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
You can build this manually with:
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):
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
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
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