Show the TechJSON schema in readthedocs

.readthedocs.yml

@@ -11,6 +11,7 @@ build:
  - pip install poetry myst-parser
  - poetry config virtualenvs.create false
  - poetry install
+ - python3 -c "from hammer.tech import TechJSON; print(TechJSON.schema_json(indent=2))" > doc/Technology/schema.json
 
 # Build documentation with Sphinx
 sphinx:

README.md

@@ -17,8 +17,8 @@ Hammer currently requires Python 3.9+.
 For a deeper dive into available options and environment configuration:
 
 * [Core Hammer settings](hammer/config/defaults.yml)
-* [Setup documentation](doc/Hammer-Basics/Hammer-Setup.md)
-* [Hammer technology library schema](hammer/tech/__init__.py)
+* [Setup documentation](https://hammer-vlsi.readthedocs.io/en/latest/Hammer-Basics/Hammer-Setup.html)
+* [Hammer technology library schema](https://hammer-vlsi.readthedocs.io/en/latest/Technology/Tech-json.html#full-schema)
 * For CAD tool settings, please see the relevant `defaults.yml` for those plugins.
 
 Hammer is an integral component of UC Berkeley Architecture Research's [Chipyard framework](https:/ucb-bar/chipyard).

doc/Hammer-Basics/Hammer-Overview.rst

@@ -12,7 +12,7 @@ Main Hammer
 
 Hammer provides the Python backend for a Hammer project and exposes a set of APIs that are typical of modern VLSI flows. These APIs are then implemented by a tool plugin and a technology plugin of the designer's choice. The structure of Hammer is meant to enable re-use and portability between technologies.
 
-Hammer takes its inputs and serializes its state in form of YML and JSON files. The designer sets a variety of settings in the form of keys in different namespaces that are designated in Hammer to control its functionality. These keys are contained in ``hammer/src/hammer-vlsi/defaults.yml``. This file shows all of the keys that are a part of main Hammer and provides sensible defaults that may be overridden or are set to null if they must be provided by the designer.
+Hammer takes its inputs and serializes its state in form of YML and JSON files. The designer sets a variety of settings in the form of keys in different namespaces that are designated in Hammer to control its functionality. These keys are contained in ``hammer/hammer/config/defaults.yml``. This file shows all of the keys that are a part of main Hammer and provides sensible defaults that may be overridden or are set to null if they must be provided by the designer.
 
 Here is an example of a snippet that would be included in the user's input configuration.
 
@@ -93,3 +93,11 @@ Finally, ``par`` designates that this is a place-and-route action.
 In this case, Hammer will write outputs to the path ``$PWD/build/par-rundir``.
 
 For the full list of Hammer command-line arguments, run `hammer-vlsi --help` or take a peek in the ``hammer/vlsi/cli_driver.py`` file.
+
+Summary
+-------
+
+The software architecture as described above is shown in the diagram below, which is taken from the DAC paper.
+
+.. image:: arch.png
+ :width: 600

doc/Technology/Tech-json.rst

@@ -3,14 +3,15 @@
 Hammer Tech JSON
 ===============================
 
-The ``tech.json`` for a given technology sets up some general information about the install of the PDK, sets up DRC rule decks, sets up pointers to PDK files, and supplies technology stackup information. For a full schema that the tech JSON supports, please see the ``TechJSON`` Pydantic model class in ``hammer/tech/__init__.py``.
+The ``tech.json`` for a given technology sets up some general information about the install of the PDK, sets up DRC rule decks, sets up pointers to PDK files, and supplies technology stackup information. 
+For the full schema of the tech JSON, please see the :ref:`full_schema` section below, which is derived from the ``TechJSON`` Pydantic BaseModel in ``hammer/tech/__init__.py``.
 
 Technology Install
 ---------------------------------
 
-The user may supply the PDK to Hammer as an already extracted directory and/or as a tarball that Hammer can automatically extract. Setting ``technology.TECH_NAME.`` ``install_dir`` and/or ``tarball_dir`` (key is setup in the defaults.yml) will fill in as the path prefix for paths supplied to PDK files in the rest of the ``tech.json``. :numref:`install-example` shows an example of the installs and tarballs from the ASAP7 plugin.
+The user may supply the PDK to Hammer as an already extracted directory and/or as a tarball that Hammer can automatically extract. Setting ``technology.TECH_NAME.`` ``install_dir`` and/or ``tarball_dir`` (key is setup in the defaults.yml) will fill in as the path prefix for paths supplied to PDK files in the rest of the ``tech.json``.
+Below is an example of the installs and tarballs from the ASAP7 plugin.
 
-.. _install-example:
 .. code-block:: json
 
  "name": "ASAP7 Library",
@@ -42,9 +43,9 @@ The ``id`` field is used within the file listings further down in the file to pr
 DRC/LVS Deck Setup
 ---------------------------------
 
-As many DRC & LVS decks for as many tools can be specified in the ``drc decks`` and ``lvs decks`` keys. Additional DRC/LVS commands can be appended to the generated run files by specifying raw text in the ``additional_drc_text`` and ``additional_lvs_text`` keys. :numref:`deck-example` shows an example of an LVS deck from the ASAP7 plugin.
+As many DRC & LVS decks for as many tools can be specified in the ``drc decks`` and ``lvs decks`` keys. Additional DRC/LVS commands can be appended to the generated run files by specifying raw text in the ``additional_drc_text`` and ``additional_lvs_text`` keys. 
+Below is an example of an LVS deck from the ASAP7 plugin.
 
-.. _deck-example:
 .. code-block:: json
 
  "lvs_decks": [
@@ -61,10 +62,9 @@ The file pointers, in this case, use the tarball prefix because Hammer will be e
 Library Setup
 ---------------------------------
 
-The ``libraries`` key also must be setup in the JSON plugin. This will tell Hammer where to find all of the relevant files for standard cells and other blocks for the VLSI flow. :numref:`library-example` shows an example of the start of the library setup and one entry from the ASAP7 plugin.
+The ``libraries`` key also must be setup in the JSON plugin. This will tell Hammer where to find all of the relevant files for standard cells and other blocks for the VLSI flow. 
+Below is an example of the start of the library setup and one entry from the ASAP7 plugin.
 
-
-.. _library-example:
 .. code-block:: json
 
  "libraries": [
@@ -118,9 +118,9 @@ For a list of pre-built library filters, refer to the properties in the ``Librar
 
 Stackup
 --------------------------------
-The ``stackups`` sets up the important metal layer information for Hammer to use. :numref:`stackups-example` shows an example of one metal layer in the ``metals`` list from the ASAP7 example tech plugin. 
+The ``stackups`` sets up the important metal layer information for Hammer to use. 
+Below is an example of one metal layer in the ``metals`` list from the ASAP7 example tech plugin. 
 
-.. _stackups-example:
 .. code-block:: json
 
  {"name": "M3", "index": 3, "direction": "vertical", "min_width": 0.072, "pitch": 0.144, "offset": 0.0, "power_strap_widths_and_spacings": [{"width_at_least": 0.0, "min_spacing": 0.072}], "power_strap_width_table": [0.072, 0.36, 0.648, 0.936, 1.224, 1.512]}
@@ -132,7 +132,6 @@ Sites
 --------------------------------
 The ``sites`` field specifies the unit standard cell size of the technology for Hammer.
 
-.. _sites-example:
 .. code-block:: json
 
  "sites": [
@@ -143,9 +142,9 @@ This is an example from the ASAP7 tech plugin in which the ``name`` parameter sp
 
 Special Cells
 --------------------------------
-The ``special_cells`` field specifies a set of cells in the technology that have special functions. :numref:`special-cells-example` shows a subset of the ASAP7 tech plugin for 2 types of cells: ``tapcell`` and ``stdfiller``.
+The ``special_cells`` field specifies a set of cells in the technology that have special functions. 
+The example below shows a subset of the ASAP7 tech plugin for 2 types of cells: ``tapcell`` and ``stdfiller``.
 
-.. _special-cells-example:
 .. code-block:: json
 
  "special_cells": [
@@ -196,3 +195,12 @@ The ``physical only cells list`` is used to denote cells that contain only physi
  "FILLER_ASAP7_75t_R", "FILLER_ASAP7_75t_L", "FILLER_ASAP7_75t_SL", "FILLER_ASAP7_75t_SRAM", 
  "FILLERxp5_ASAP7_75t_R", "FILLERxp5_ASAP7_75t_L", "FILLERxp5_ASAP7_75t_SL", "FILLERxp5_ASAP7_75t_SRAM"
  ],
+
+.. _full_schema:
+Full Schema
+-----------
+
+Note that in the the schema tables presented below, items with ``#/definitions/<class_name>`` are defined in other schema tables. This is done for documentation clarity, but in your JSON file, those items would be hierarchically nested.
+
+.. jsonschema:: schema.json
+ :lift_definitions:

doc/conf.py

@@ -31,7 +31,9 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
- "myst_parser"
+ "myst_parser",
+ "sphinx-jsonschema",
+ "sphinx_rtd_size"
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -57,6 +59,8 @@
  'collapse_navigation': False,
 }
 
+sphinx_rtd_size_width = "1200px"
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".