[docs/ci] cleanup docs and add ci to check it (#485)

.circleci/config.yml

@@ -145,6 +145,17 @@ jobs:
                 name: Check that the tutorial-setup patches apply
                 command: |
                     scripts/tutorial-setup.sh
+    documentation-check:
+        executor: main-env
+        steps:
+            - checkout
+            - run:
+                name: Check that documentation builds with no warnings/errors
+                command: |
+                    sudo apt-get update -y
+                    sudo apt-get install -y python3-pip
+                    sudo pip3 install -r docs/requirements.txt
+                    make -C docs html
 
     install-riscv-toolchain:
         executor: main-env
@@ -357,6 +368,9 @@ workflows:
             # Attempt to apply the tutorial patches
             - tutorial-setup-check
 
+            # Check that documentation builds
+            - documentation-check
+
             # Build extra tests
             - build-extra-tests:
                 requires:

docs/Generators/IceNet.rst

@@ -78,7 +78,7 @@ Configuration
 To add IceNIC to your design, add ``HasPeripheryIceNIC`` to your lazy module
 and ``HasPeripheryIceNICModuleImp`` to the module implementation. If you
 are confused about the distinction between lazy module and module
-implementation, refer to :ref:`Cake Pattern`.
+implementation, refer to :ref:`Cake Pattern / Mixin`.
 
 Then add the ``WithIceNIC`` config fragment to your configuration. This will
 define ``NICKey``, which IceNIC uses to determine its parameters. The config fragment

docs/Makefile

@@ -2,8 +2,8 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -w warnings.txt
+SPHINXOPTS    = -w warnings.txt -n -W
-SPHINXBUILD   = python -msphinx
+SPHINXBUILD   = python3 -msphinx
 SPHINXPROJ    = Chipyard
 SOURCEDIR     = .
 BUILDDIR      = _build

docs/TileLink-Diplomacy-Reference/Widgets.rst

@@ -270,7 +270,7 @@ the client to see a particular width.
 
 **Example Usage:**
 
-.. code-block::
+.. code-block:: scala
 
     // Assume the manager node sets beatBytes to 8
     // With WidthWidget, client sees beatBytes of 4

docs/Tools/Barstools.rst

@@ -131,5 +131,5 @@ This, unfortunately, breaks the process-agnostic RTL abstraction, so it is recom
 The simplest way to do this is to have a config fragment that when included updates instantiates the IO cells and connects them in the test harness.
 When simulating chip-specific designs, it is important to include the IO cells.
 The IO cell behavioral models will often assert if they are connected incorrectly, which is a useful runtime check.
-They also keep the IO interface at the chip and test harness boundary (see :ref:`Separating the top module from the test harness`) consistent after synthesis and place-and-route,
+They also keep the IO interface at the chip and test harness boundary (see :ref:`Separating the Top module from the TestHarness module`) consistent after synthesis and place-and-route,
 which allows the RTL simulation test harness to be reused.

docs/VLSI/Building-A-Chip.rst

@@ -45,8 +45,8 @@ It is possible to write this IR directly, or to generate it using simple python
 While we certainly look forward to having a more featureful toolkit, we have built many chips to date in this way.
 
 
-Running the VLSI flow
+Running the VLSI tool flow
----------------------
+--------------------------
 
 For the full documentation on how to use the VLSI tool flow, see the `Hammer Documentation <https://hammer-vlsi.readthedocs.io/>`__.
 For an example of how to use the VLSI in the context of Chipyard, see :ref:`ASAP7 Tutorial`.