[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

@@ -169,7 +169,7 @@ transactions.
  - ``minSize: Int`` - Minimum size of transfers supported by all outward managers.
  - ``maxSize: Int`` - Maximum size of transfers supported after the Fragmenter is applied.
  - ``alwaysMin: Boolean`` - (optional) Fragment all requests down to minSize (else fragment to maximum supported by manager). (default: false)
- - ``earlyAck: EarlyAck.T`` - (optional) Should a multibeat Put be acknowledged on the first beat or last beat? 
+ - ``earlyAck: EarlyAck.T`` - (optional) Should a multibeat Put be acknowledged on the first beat or last beat?
    Possible values (default: ``EarlyAck.None``):
 
     - ``EarlyAck.AllPuts`` - always acknowledge on first beat.
@@ -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
@@ -398,11 +398,11 @@ package, not the ``freechips.rocketchip.tilelink`` package like the others.
  - ``size: Int`` - The size of the memory in bytes
  - ``contentsDelayed: => Seq[Byte]`` - A function which, when called generates
    the byte contents of the ROM.
- - ``executable: Boolean`` - (optional) Specify whether the CPU can fetch 
+ - ``executable: Boolean`` - (optional) Specify whether the CPU can fetch
    instructions from the ROM (default: ``true``).
- - ``beatBytes: Int`` - (optional) The width of the interface in bytes. 
+ - ``beatBytes: Int`` - (optional) The width of the interface in bytes.
    (default: 4).
- - ``resources: Seq[Resource]`` - (optional) Sequence of resources to add to 
+ - ``resources: Seq[Resource]`` - (optional) Sequence of resources to add to
    the device tree.
 
 **Example Usage:**
@@ -429,13 +429,13 @@ The TLRAM and AXI4RAM widgets provide read-write memories implemented as SRAMs.
 **Arguments:**
 
  - ``address: AddressSet`` - The address range that this RAM will cover.
- - ``cacheable: Boolean`` - (optional) Can the contents of this RAM be cached. 
+ - ``cacheable: Boolean`` - (optional) Can the contents of this RAM be cached.
    (default: ``true``)
- - ``executable: Boolean`` - (optional) Can the contents of this RAM be fetched 
+ - ``executable: Boolean`` - (optional) Can the contents of this RAM be fetched
    as instructions. (default: ``true``)
- - ``beatBytes: Int`` - (optional) Width of the TL/AXI4 interface in bytes. 
+ - ``beatBytes: Int`` - (optional) Width of the TL/AXI4 interface in bytes.
    (default: 4)
- - ``atomics: Boolean`` - (optional, TileLink only) Does the RAM support 
+ - ``atomics: Boolean`` - (optional, TileLink only) Does the RAM support
    atomic operations? (default: ``false``)
 
 **Example Usage:**

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`.