Documentation Updates

README.md

@@ -11,119 +11,51 @@
     <a href="https://invite.skywater.tools"><img src="https://img.shields.io/badge/Community-Open%20Source%20Silicon%20Slack-ff69b4?logo=slack" alt="Invite to the Open Source Silicon Slack"/></a>
 </p>
 
-CACE is a set of python scripts that take an input file in the
-CACE 4.0 format and uses the information found there in combination with CACE-compatible testbenches and analysis scripts to characterize a circuit and to produce a datasheet showing the circuit performance.
+CACE is a framework for analog and mixed-signal circuits that enables automatic characterization under various conditions and with Monte Carlo and mismatch analysis. After all parameters have been run under the given conditions, CACE will generate a summary showing the circuit performance.
 
-## Installation
-
-You'll need the following:
-
-- Python 3.8 or higher with PIP and Tkinter
-
-CACE can be installed directly from PyPI:
-
-	$ python3 -m pip install --upgrade cace
-Prerequisite design tools:
-
-- xschem:  [https://github.com/stefanschippers/xschem](https://github.com/stefanschippers/xschem)
-- ngspice: git://git.code.sf.net/p/ngspice/ngspice
-- magic:	 [https://github.com/RTimothyEdwards/magic](https://github.com/RTimothyEdwards/magic)
-
-Some of the measurements require:
-
-- octave: [https://octave.org/](https://octave.org/)
-
-## Usage
-
-If installed as Python package, CACE can be started from the command line using:
-
-```
-$ cace
-```
-
-Or to start the GUI:
-
-```
-$ cace-gui
-```
-
-Information on how to use CACE can be found in the documentation at [cace.readthedocs.io](https://cace.readthedocs.io/). 
-
-## Development
-
-### Dependencies
-
-> [!IMPORTANT]
-> You may need to set up a Python [virtual environment](https://docs.python.org/3/library/venv.html).
+> [!NOTE]
+> The latest documentation can be viewed online at [cace.readthedocs.io](https://cace.readthedocs.io/). 
 
-To install the dependencies for CACE, run:
+## Installation
 
-	$ make dependencies
+CACE currently supports two primary methods of installation for it and its dependencies.
 
-### Python Package
+Please read the installation instruction in the documentation under ["Installation Overview"](https://cace.readthedocs.io/en/latest/getting_started/index.html).
 
-To build the Python package, run:
+### Nix (Recommended)
 
-```
-$ make build
-```
+Works for macOS and Linux (x86-64 and aarch64) as well for Windows via WSL2. Recommended, as it is more integrated with your filesystem and overall has less upload and download deltas.
 
-To install the package, run:
+See [Nix-based installation](https://cace.readthedocs.io/en/latest/getting_started/common/nix_installation/index.html) in the docs for more info.
 
-```
-$ make install
-```
+### Python-only Installation
 
-To install the package in editable mode, run:
+You'll need to bring your own compiled utilities, but otherwise, simply install CACE as follows:
 
+```console
+	python3 -m pip install --upgrade cace
 ```
-$ make editable
-```
-
-### Documentation
-
-To build the documentation, run:
 
-```
-$ make docs
-```
+## Usage
 
-To host the docs, run:
+To invoke the CLI:
 
-```
-$ make host-docs
+```console
+cace [datasheet] [output] [options]
 ```
 
-To automatically refresh the docs upon changes, run:
+To invoke the GUI:
 
-```
-$ make auto-docs
+```console
+cace-gui [datasheet] [options]
 ```
 
-> [!NOTE]
-> The latest documentation can be viewed online at [cace.readthedocs.io](https://cace.readthedocs.io/). 
+For more information about the usage of CACE with either the CLI or the GUI please have a look at ["Usage Guides"](https://cace.readthedocs.io/en/latest/usage_guides/index.html) in the documentation.
 
 ## Examples
 
-The following repositories contain example circuit designs, each having a "cace/" subdirectory with a specification input file in the format described below, and a set of testbench schematics which are used by CACE to measure all specified electrical and physical parameters, generate results, and analyze them to determine circuit performance over corners.
+There exist already numerous designs that use CACE. We have assembled a list of different designs that you can use as reference: [Example Designs](https://cace.readthedocs.io/examples/index.html). 
 
-> [!NOTE]
-> Example repositories, like CACE itself, are currently a work in progress.
+## License
 
-All repositories are rooted at: [https://github.com/RTimothyEdwards/](https://github.com/RTimothyEdwards/).
-
-Example circuit repositories:
-
-- [sky130_ef_ip__instramp](https://github.com/RTimothyEdwards/sky130_ef_ip__instramp)		Instrumentation amplifier
-- [sky130_ef_ip__rdac3v_8bit](https://github.com/RTimothyEdwards/sky130_ef_ip__rdac3v_8bit)	8-bit resistor ladder DAC
-- sky130_ef_ip__samplehold	sample-and-hold circuit
-- sky130_ef_ip__driveramp		Rail-to-rail driver amplifier
-- sky130_ef_ip__ccomp3v		Rail-to-rail continuous comparator
-- sky130_ef_ip__rc_osc_500k	R-C oscillator, 500kHz nominal output
-- sky130_ef_ip__xtal_osc_16M	Crystal oscillator, 4 to 15MHz
-- sky130_ef_ip__xtal_osc_32k	Crystal oscillator, 32kHz
-
-Each of these repositories contains a circuit designed with the SkyWater sky130 process open PDK, and contains schematics, layout, and CACE characterization.
-
-> [!NOTE]
-> These repositories are a work in progress, and may not exist yet or may not have a characterization setup for CACE.
+[The Apache License, version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt).

docs/source/dev/build.md

@@ -0,0 +1,31 @@
+# Build CACE
+
+If you are using nix, the package will be builded when you run `nix-shell`.
+
+---
+
+If not, you may need to set up a Python [virtual environment](https://docs.python.org/3/library/venv.html).
+
+To install the dependencies for CACE, run:
+
+```
+$ make dependencies
+```
+
+To build the Python package, run:
+
+```
+$ make build
+```
+
+To install the package, run:
+
+```
+$ make install
+```
+
+To install the package in editable mode, run:
+
+```
+$ make editable
+```

docs/source/dev/docs.md

@@ -0,0 +1,27 @@
+# Documentation
+
+If you are using nix, you can get the environmen to build the docs by running `nix develop .#docs`. Otherwise, you will need to install the dependencies via:
+
+```
+$ make dependencies
+```
+
+---
+
+To build the documentation, run:
+
+```
+$ make docs
+```
+
+To host the docs, run:
+
+```
+$ make host-docs
+```
+
+To automatically refresh the docs upon changes, run:
+
+```
+$ make auto-docs
+```

docs/source/dev/index.md

@@ -6,6 +6,8 @@ If you want to start developing CACE, please read these pages.
 :glob:
 :maxdepth: 2
 
+build
+docs
 coding_style
 codebase
 ```

docs/source/examples/index.md

@@ -0,0 +1,16 @@
+# Examples
+
+The following repositories contain example circuit designs, each having a `cace/` subdirectory with a specification input (the datasheet), and a set of testbench schematics which are used by CACE to measure all specified electrical and physical parameters, generate results, and analyze them to determine circuit performance over corners.
+
+Example circuit repositories:
+
+| Design                     | Description                | PDK |
+|----------------------------|----------------------------|-----|
+| [ota-5t](https://github.com/mole99/ota-5t/)                     | A simple 5-transistor OTA                | Sky130A |
+| [sky130_ef_ip__opamp](https://github.com/RTimothyEdwards/sky130_ef_ip__opamp)                     | Operational Amplifier                | Sky130A |
+| [sky130_ef_ip__rdac3v_8bit](https://github.com/RTimothyEdwards/sky130_ef_ip__rdac3v_8bit)                     | 8-bit resistor ladder DAC                | Sky130A |
+| ...                     | ...                |
+
+```{note}
+Send us a PR if you want to add your design!
+```

docs/source/getting_started/common/nix_installation/_common.md

@@ -0,0 +1,61 @@
+````{admonition} If you already have Nix set up…
+:class: note 
+
+You will need to enable CACE's
+[Binary Cache](https://nixos.wiki/wiki/Binary_Cache) manually.
+
+If you don't know what that means:
+
+We use a service called Cachix, which allows the reproducible Nix builds to be
+stored on a cloud server so you do not have to build CACE's dependencies
+from scratch on every computer, which will take a long time.
+
+First, you want to install Cachix by running the following in your terminal:
+
+```console
+$ nix-env -f "<nixpkgs>" -iA cachix
+```
+
+Then set up the binary cache as follows (the cache is shared with openlane):
+
+```console
+$ sudo env PATH="$PATH" cachix use openlane
+```
+
+…and restart the Nix daemon.
+
+```console
+$ sudo pkill nix-daemon
+```
+
+---
+
+If you *do* know what this means, the values are as follows:
+
+```ini
+extra-substituters = https://openlane.cachix.org
+extra-trusted-public-keys = openlane.cachix.org-1:qqdwh+QMNGmZAuyeQJTH9ErW57OWSvdtuwfBKdS254E=
+```
+
+Make sure to restart `nix-daemon` after updating `/etc/nix/nix.conf`.
+
+```console
+$ sudo pkill nix-daemon
+```
+
+````
+
+# Cloning CACE
+
+With git installed, just run the following:
+
+```console
+$ git clone https://github.com/efabless/cace
+```
+
+That's it. Whenever you want to use CACE, run `nix-shell` in the repository root
+directory and you'll have a full CACE environment. The first time might take
+around 10 minutes while binaries are pulled from the cache.
+
+To quickly test your installation, simply run `cace --help` in the nix
+shell.