[docs] Make the link to initial setup stand out. (#533)

* [docs] Make the link to initial setup stand out.
* [docs] Merge the two quick starts
* More descriptive text about the setup link
Co-authored-by: alonamid <alonamid@eecs.berkeley.edu>

docs/Chipyard-Basics/Initial-Repo-Setup.rst

@@ -23,10 +23,10 @@ In Ubuntu/Debian-based platforms (Ubuntu), we recommend installing the following
 
 .. Note:: When running on an Amazon Web Services EC2 FPGA-development instance (for FireSim), FireSim includes a machine setup script that will install all of the aforementioned dependencies (and some additional ones).
 
-Checking out the sources
+Setting up the Chipyard Repo
-------------------------
+-------------------------------------------
 
-After cloning this repo, you will need to initialize all of the submodules.
+Start by fetching Chipyard's sources. Run:
 
 .. code-block:: shell
 
@@ -34,6 +34,8 @@ After cloning this repo, you will need to initialize all of the submodules.
     cd chipyard
     ./scripts/init-submodules-no-riscv-tools.sh
 
+This will initialize and checkout all of the necessary git submodules.
+
 When updating Chipyard to a new version, you will also want to rerun this script to update the submodules.
 Using git directly will try to initialize all submodules; this is not recommended unless you expressly desire this behavior.
 
@@ -46,15 +48,41 @@ The `toolchains` directory contains toolchains that include a cross-compiler too
 Currently there are two toolchains, one for normal RISC-V programs, and another for Hwacha (``esp-tools``).
 For custom installations, Each tool within the toolchains contains individual installation procedures within its README file.
 To get a basic installation (which is the only thing needed for most Chipyard use-cases), just the following steps are necessary.
+This will take about 20-30 minutes. You can expedite the process by setting a ``make`` environment variable to use parallel cores: ``export MAKEFLAGS=-j8``.
 
 .. code-block:: shell
 
     ./scripts/build-toolchains.sh riscv-tools # for a normal risc-v toolchain
 
-    # OR
+.. Note:: If you are planning to use the Hwacha vector unit, or other RoCC-based accelerators, you should build the esp-tools toolchain by adding the ``esp-tools`` argument to the script above.
-
+  If you are running on an Amazon Web Services EC2 instance, intending to use FireSim, you can also use the ``--ec2fast`` flag for an expedited installation of a pre-compiled toolchain.
-    ./scripts/build-toolchains.sh esp-tools # for a modified risc-v toolchain with Hwacha vector instructions
 
 Once the script is run, a ``env.sh`` file is emitted that sets the ``PATH``, ``RISCV``, and ``LD_LIBRARY_PATH`` environment variables.
-You can put this in your ``.bashrc`` or equivalent environment setup file to get the proper variables.
+You can put this in your ``.bashrc`` or equivalent environment setup file to get the proper variables, or directly include it in your current environment:
+
+.. code-block:: shell
+
+    source ./env.sh
+
 These variables need to be set for the ``make`` system to work properly.
+
+What's Next?
+-------------------------------------------
+
+This depends on what you are planning to do with Chipyard.
+
+* If you intend to run a simulation of one of the vanilla Chipyard examples, go to :ref:`sw-rtl-sim-intro` and follow the instructions.
+
+* If you intend to run a simulation of a custom Chipyard SoC Configuration, go to :ref:`Simulating A Custom Project` and follow the instructions.
+
+* If you intend to run a full-system FireSim simulation, go to :ref:`firesim-sim-intro` and follow the instructions.
+
+* If you intend to add a new accelerator, go to :ref:`customization` and follow the instructions.
+
+* If you want to learn about the structure of Chipyard, go to :ref:`chipyard-components`.
+
+* If you intend to change the generators (BOOM, Rocket, etc) themselves, see :ref:`generator-index`.
+
+* If you intend to run a tutorial VLSI flow using one of the Chipyard examples, go to :ref:`tutorial` and follow the instructions.
+
+* If you intend to build a chip using one of the vanilla Chipyard examples, go to :ref:`build-a-chip` and follow the instructions.

docs/_static/css/custom.css

@@ -0,0 +1,6 @@
+.important {
+  font-size: 175%;
+}
+.important p{
+  font-size: 100%;
+}

docs/conf.py

@@ -106,6 +106,9 @@ html_theme_options = {
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+html_css_files = [
+        'css/custom.css',
+]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/index.rst

@@ -10,88 +10,8 @@ Welcome to Chipyard's documentation!
 
 Chipyard is a framework for designing and evaluating full-system hardware using agile teams.
 It is composed of a collection of tools and libraries designed to provide an integration between open-source and commercial tools for the development of systems-on-chip.
-New to Chipyard? Jump to the :ref:`Chipyard Basics` page for more info.
-
-Quick Start
-===============================
-
-System Requirements
--------------------------------------------
-
-Chipyard is developed and tested on Linux-based systems.
-
-.. Warning:: It is possible to use this on macOS or other BSD-based systems, although GNU tools will need to be installed; it is also recommended to install the RISC-V toolchain from ``brew``.
-
-.. Warning:: Working under Windows is not recommended.
-
-Setting up the Chipyard Repo
--------------------------------------------
-
-Start by fetching Chipyard's sources. Run:
-
-.. code-block:: shell
-
-    git clone https://github.com/ucb-bar/chipyard.git
-    cd chipyard
-    ./scripts/init-submodules-no-riscv-tools.sh
-
-This will initialize and checkout all of the necessary git submodules.
-
-Installing Dependencies
--------------------------------------------
-Installing the recommended dependencies on Ubuntu/Debian-based platforms:
-
-.. code-block:: shell
-
-    ./scripts/ubuntu-req.sh
-    
-Installing the recommended dependencies on CentOS-based platforms:
-
-.. code-block:: shell
-
-   ./scripts/centos-req.sh
-
-Installing the RISC-V Tools
--------------------------------------------
-
-We need to install the RISC-V toolchain in order to be able to run RISC-V programs using the Chipyard infrastructure.
-This will take about 20-30 minutes. You can expedite the process by setting a ``make`` environment variable to use parallel cores: ``export MAKEFLAGS=-j8``.
-To build the toolchains, you should run:
-
-.. code-block:: shell
-
-    ./scripts/build-toolchains.sh
-
-.. Note:: If you are planning to use the Hwacha vector unit, or other RoCC-based accelerators, you should build the esp-tools toolchain by adding the ``esp-tools`` argument to the script above.
-  If you are running on an Amazon Web Services EC2 instance, intending to use FireSim, you can also use the ``--ec2fast`` flag for an expedited installation of a pre-compiled toolchain.
-
-Finally, set up Chipyard's environment variables and put the newly built toolchain on your path:
-
-.. code-block:: shell
-
-    source ./env.sh
-
-What's Next?
--------------------------------------------
-
-This depends on what you are planning to do with Chipyard.
-
-* If you intend to run a simulation of one of the vanilla Chipyard examples, go to :ref:`sw-rtl-sim-intro` and follow the instructions.
-
-* If you intend to run a simulation of a custom Chipyard SoC Configuration, go to :ref:`Simulating A Custom Project` and follow the instructions.
-
-* If you intend to run a full-system FireSim simulation, go to :ref:`firesim-sim-intro` and follow the instructions.
-
-* If you intend to add a new accelerator, go to :ref:`customization` and follow the instructions.
-
-* If you want to learn about the structure of Chipyard, go to :ref:`chipyard-components`.
-
-* If you intend to change the generators (BOOM, Rocket, etc) themselves, see :ref:`generator-index`.
-
-* If you intend to run a tutorial VLSI flow using one of the Chipyard examples, go to :ref:`tutorial` and follow the instructions.
-
-* If you intend to build a chip using one of the vanilla Chipyard examples, go to :ref:`build-a-chip` and follow the instructions.
 
+.. IMPORTANT:: **New to Chipyard?** Jump to the :ref:`Initial Repository Setup` page for setup instructions.
 
 Getting Help
 ------------

docs/requirements.txt

@@ -1,4 +1,4 @@
-Sphinx==1.7.4
+Sphinx==1.8.5
 Pygments==2.2.0
 sphinx-autobuild
 sphinx_rtd_theme==0.2.5b1