docs nit fixes (#2362)

* favicon

* fix image bg on dark mode

* keep pdf generation

* remove dead links in ToC

Author: jimfangx

docs/Customization/Dsptools-Blocks.rst

@@ -21,6 +21,7 @@ Chipyard has example designs that integrate a ``DspBlock`` to a rocketchip-based
 .. figure:: ../_static/images/fir-block-diagram.svg
     :align: center
     :alt: Block diagram showing how FIR is integrated with rocket.
+    :class: diagram-white-background
     :width: 400px
 
 For this example, we will show you how to connect a simple FIR filter created using Dsptools as an MMIO peripheral as shown in the figure above. The full code can be found in `generators/chipyard/src/main/scala/example/dsptools/GenericFIR.scala <https://ucb.bar/chipyard/generators/chipyard/src/main/scala/example/dsptools/GenericFIR.scala>`_. That being said, one could substitute any module with a ready valid interface in the place of the FIR and achieve the same results. As long as the read and valid signals of the module are attached to those of a corresponding ``DSPBlock`` wrapper, and that wrapper is placed in a chain with a ``ReadQueue`` and a ``WriteQueue``, following the general outline establised by these steps will allow you to interact with that block as a memory mapped IO.

docs/Generators/BOOM.rst

@@ -2,6 +2,7 @@ Berkeley Out-of-Order Machine (BOOM)
 ==============================================
 
 .. image:: ../_static/images/boom-pipeline-detailed.png
+   :class: diagram-white-background
 
 The `Berkeley Out-of-Order Machine (BOOM) <https://boom-core.org/>`__ is a synthesizable and parameterizable open source RV64GC RISC-V core written in the Chisel hardware construction language.
 It serves as a drop-in replacement to the Rocket core given by Rocket Chip (replaces the RocketTile with a BoomTile).
@@ -10,4 +11,4 @@ Like the R10k and the 21264, BOOM is a unified physical register file design (al
 Conceptually, BOOM is broken up into 10 stages: Fetch, Decode, Register Rename, Dispatch, Issue, Register Read, Execute, Memory, Writeback and Commit.
 However, many of those stages are combined in the current implementation, yielding seven stages: Fetch, Decode/Rename, Rename/Dispatch, Issue/RegisterRead, Execute, Memory and Writeback (Commit occurs asynchronously, so it is not counted as part of the “pipeline”).
 
-Additional information about the BOOM micro-architecture can be found in the `BOOM documentation pages <https://docs.boom-core.org/>`__. A set of example BOOM Core configurations can be found at `generators/chipyard/src/main/scala/config/BoomConfigs.scala <https://github.com/ucb-bar/chipyard/blob/main/generators/chipyard/src/main/scala/config/BoomConfigs.scala>`__.
+Additional information about the BOOM micro-architecture can be found in the `BOOM documentation pages <https://docs.boom-core.org/>`__. A set of example BOOM Core configurations can be found at `generators/chipyard/src/main/scala/config/BoomConfigs.scala <https://github.com/ucb-bar/chipyard/blob/main/generators/chipyard/src/main/scala/config/BoomConfigs.scala>`__.

docs/Generators/IceNet.rst

@@ -7,6 +7,7 @@ in `FireSim <https://fires.im/>`_ for multi-node networked simulation.
 A diagram of IceNet's microarchitecture is shown below.
 
 .. image:: ../_static/images/nic-design.png
+   :class: diagram-white-background
 
 There are four basic parts of the NIC: the :ref:`Generators/IceNet:Controller`, which takes requests
 from and sends responses to the CPU; the :ref:`Generators/IceNet:Send Path`, which reads data from

docs/Generators/Rocket-Chip.rst

@@ -11,7 +11,11 @@ out-of-order core generator or some other custom CPU generator instead.
 
 A detailed diagram of a typical Rocket Chip system is shown below.
 
-.. image:: ../_static/images/rocketchip-diagram.png
+.. raw:: html
+
+   <img alt="Diagram of a typical Rocket Chip system"
+        class="diagram-white-background"
+        src="../_static/images/rocketchip-diagram.png">
 
 Tiles
 -----

docs/README.md

@@ -35,6 +35,17 @@ cd docs
 npm run build
 ```
 
+Read the Docs also builds downloadable PDF and EPUB versions directly from
+the RST sources using Sphinx. To build the same formats locally:
+
+```sh
+cd docs
+python -m sphinx -M latexpdf . _build
+python -m sphinx -M epub . _build
+```
+
+The PDF build requires a local LaTeX installation.
+
 ## Debugging RST with Sphinx
 
 The original Sphinx live-reload preview is still available for debugging RST

docs/_static/css/custom.css

@@ -4,3 +4,12 @@
 .important p{
   font-size: 100%;
 }
+
+.chipyard-logo-dark {
+  display: none;
+}
+
+img.diagram-white-background {
+  background-color: white;
+  border: 1px solid white;
+}

docs/astro.config.mjs

@@ -1,9 +1,64 @@
 import starlight from '@astrojs/starlight';
 import { defineConfig } from 'astro/config';
-import { readFileSync } from 'node:fs';
+import { createReadStream, readFileSync, statSync } from 'node:fs';
+import { extname, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { sidebar } from './src/sidebar.mjs';
 
+const sphinxPublicRoot = resolve(fileURLToPath(new URL('./public/sphinx/', import.meta.url)));
+const sphinxContentTypes = {
+  '.css': 'text/css; charset=utf-8',
+  '.gif': 'image/gif',
+  '.html': 'text/html; charset=utf-8',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+};
+
+function serveSphinxAssets() {
+  return {
+    name: 'serve-sphinx-assets',
+    configureServer(server) {
+      server.middlewares.use((request, response, next) => {
+        const pathname = new URL(request.url || '/', 'http://localhost').pathname;
+        if (!pathname.startsWith('/sphinx/')) return next();
+
+        let relativePath;
+        try {
+          relativePath = decodeURIComponent(pathname.slice('/sphinx/'.length));
+        } catch {
+          return next();
+        }
+
+        const filePath = resolve(sphinxPublicRoot, relativePath);
+        if (!filePath.startsWith(sphinxPublicRoot + sep)) return next();
+
+        let file;
+        try {
+          file = statSync(filePath);
+        } catch {
+          return next();
+        }
+        if (!file.isFile()) return next();
+
+        response.statusCode = 200;
+        response.setHeader('Content-Length', file.size);
+        response.setHeader(
+          'Content-Type',
+          sphinxContentTypes[extname(filePath).toLowerCase()] || 'application/octet-stream',
+        );
+        createReadStream(filePath).on('error', next).pipe(response);
+      });
+    },
+  };
+}
+
 function getBasePath() {
   if (process.env.DOCS_BASE) return process.env.DOCS_BASE;
   if (process.env.READTHEDOCS !== 'True') return undefined;
@@ -25,11 +80,15 @@ const legacyRedirects = Object.fromEntries(
 export default defineConfig({
   site: process.env.DOCS_SITE_URL || 'https://chipyard.readthedocs.io',
   base,
+  vite: {
+    plugins: [serveSphinxAssets()],
+  },
   redirects: legacyRedirects,
   integrations: [
     starlight({
       title: 'Chipyard',
       description: 'Chipyard documentation',
+      favicon: '/favicon/favicon.svg',
       logo: {
         dark: './_static/images/chipyard-logo-dark.svg',
         light: './_static/images/chipyard-logo.svg',
@@ -61,6 +120,44 @@ export default defineConfig({
         maxHeadingLevel: 4,
       },
       head: [
+        {
+          tag: 'link',
+          attrs: {
+            rel: 'icon',
+            type: 'image/png',
+            sizes: '96x96',
+            href: `${basePrefix}/favicon/favicon-96x96.png`,
+          },
+        },
+        {
+          tag: 'link',
+          attrs: {
+            rel: 'shortcut icon',
+            href: `${basePrefix}/favicon/favicon.ico`,
+          },
+        },
+        {
+          tag: 'link',
+          attrs: {
+            rel: 'apple-touch-icon',
+            sizes: '180x180',
+            href: `${basePrefix}/favicon/apple-touch-icon.png`,
+          },
+        },
+        {
+          tag: 'meta',
+          attrs: {
+            name: 'apple-mobile-web-app-title',
+            content: 'Chipyard',
+          },
+        },
+        {
+          tag: 'link',
+          attrs: {
+            rel: 'manifest',
+            href: `${basePrefix}/favicon/site.webmanifest`,
+          },
+        },
         {
           tag: 'meta',
           attrs: {

docs/index.rst

@@ -1,7 +1,12 @@
 Welcome to Chipyard's documentation (version "|version|")!
 ==========================================================
 
-.. image:: ./_static/images/chipyard-logo.svg
+.. raw:: html
+
+   <img alt="Chipyard" class="chipyard-logo-light"
+        src="_static/images/chipyard-logo.svg">
+   <img alt="Chipyard" class="chipyard-logo-dark"
+        src="_static/images/chipyard-logo-dark.svg">
 
 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.
@@ -42,11 +47,3 @@ Table of Contents
    TileLink-Diplomacy-Reference/index
 
    Prototyping/index
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`