Merge pull request #27 from mole99/update-docs

Update the Documentation
efabless · Mar 12, 2024 · 7f2846a · 7f2846a
2 parents f058b82 + d4415df
commit 7f2846a
Show file tree

Hide file tree

Showing 5 changed files with 134 additions and 83 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -24,10 +24,10 @@ jobs:
         with:
           python-version: "3.8"
       - name: Install Dependencies
-        run: make venv
+        run: make dependencies
       - name: Lint
         run: |
-          PATH=$PWD/venv/bin:$PATH make lint
+          make lint
 
   build:
     runs-on: ubuntu-22.04
@@ -45,16 +45,16 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install Dependencies
-        run: make venv
+        run: make dependencies
       - name: Build Package
         run: |
-          PATH=$PWD/venv/bin:$PATH make build
+          make build
       - name: Install Package
         run: |
-          PATH=$PWD/venv/bin:$PATH make install
+          make install
       - name: Run CACE
         run: |
-          PATH=$PWD/venv/bin:$PATH cace -help
+          cace -help
 
   docs:
     runs-on: ubuntu-22.04
@@ -68,13 +68,7 @@ jobs:
         with:
           python-version: 3.8
       - name: Install Dependencies
-        run: make venv
-      - name: Build Package
-        run: |
-          PATH=$PWD/venv/bin:$PATH make build
-      - name: Install Package
-        run: |
-          PATH=$PWD/venv/bin:$PATH make install
+        run: make dependencies
       - name: Build Documentation
         run: |
           make docs
diff --git a/Makefile b/Makefile
@@ -1,5 +1,5 @@
-.PHONY: init
-init:
+.PHONY: dependencies
+dependencies:
 	pip3 install -r requirements.txt
 	pip3 install -r requirements_dev.txt
 	pip3 install -r requirements_docs.txt
@@ -32,24 +32,13 @@ editable:
 upload:
 	python3 -m twine upload --repository pypi dist/*
 
-venv: venv/manifest.txt
-venv/manifest.txt: ./requirements_docs.txt ./requirements_dev.txt ./requirements.txt
-	rm -rf venv
-	python3 -m venv ./venv
-	PYTHONPATH= ./venv/bin/python3 -m pip install --upgrade pip
-	PYTHONPATH= ./venv/bin/python3 -m pip install --upgrade -r ./requirements_docs.txt
-	PYTHONPATH= ./venv/bin/python3 -m pip install --upgrade -r ./requirements_dev.txt
-	PYTHONPATH= ./venv/bin/python3 -m pip install --upgrade -r ./requirements.txt
-	PYTHONPATH= ./venv/bin/python3 -m pip freeze > $@
-	@echo ">> Venv prepared."
-
 .PHONY: docs
-docs: venv
-	. venv/bin/activate; $(MAKE) -C docs html
+docs:
+	$(MAKE) -C docs html
 
 .PHONY: host-docs
-host-docs: venv
-	. venv/bin/activate; python3 -m http.server --directory ./docs/build/html
+host-docs:
+	python3 -m http.server --directory ./docs/build/html
 
 .PHONY: clean
 clean:

diff --git a/README.md b/README.md
@@ -2,6 +2,8 @@
 <h2 align="center">Circuit Automatic Characterization Engine</h2>
 <p align="center">
     <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0"/></a>
+    <img src="https://github.com/efabless/cace/actions/workflows/ci.yaml/badge.svg?branch=main" alt="GitHub Actions Status Badge" />
+    <a href="https://cace.readthedocs.io/"><img src="https://readthedocs.org/projects/cace/badge/?version=latest" alt="Documentation Build Status Badge"/></a>
     <a href="https://www.python.org"><img src="https://img.shields.io/badge/Python-3.8-3776AB.svg?style=flat&logo=python&logoColor=white" alt="Python 3.8 or higher" /></a>
     <a href="https://github.com/grantjenks/blue"><img src="https://img.shields.io/badge/code%20style-blue-blue.svg" alt="Code Style: blue"/></a>
 </p>
@@ -41,23 +43,20 @@ 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
 
-To install the dependencies for CACE, run:
-
-	$ pip3 install -r requirements.txt
+> [!IMPORTANT]
+> You may need to set up a Python [virtual environment](https://docs.python.org/3/library/venv.html).
 
-To install the dependencies to build CACE, run:
-
-	$ pip3 install -r requirements_dev.txt
-
-To install the dependencies to build the documentation for CACE, run:
+To install the dependencies for CACE, run:
 
-	$ pip3 install -r requirements_docs.txt
+	$ make dependencies
 
-### CACE
+### Python Package
 
 To build the Python package, run:
 
@@ -77,10 +76,26 @@ To install the package in editable mode, run:
 $ make editable
 ```
 
+### Documentation
+
+To build the documentation, run:
+
+```
+$ make docs
+```
+
+To host the docs, run:
+
+```
+make host-docs
+```
+
+> [!NOTE]
+> The documentation can be viewed online at [cace.readthedocs.io](https://cace.readthedocs.io/). 
 
 ## CACE GUI syntax
 
-	/path/to/cace_gui.py [path/to/project.txt]
+    $ cace-gui [path/to/project.txt]
 
 	where optional file project.txt (normally <name_of_project>.txt
 	where <name_of_project> is the name of the circuit to be
@@ -103,7 +118,7 @@ $ make editable
 
 ## CACE command line syntax
 
-	/path/to/cace.py <filename_in> <filename_out> [options]
+	$ cace <filename_in> <filename_out> [options]
 
 	where <filename_in> is a format 4.0 ASCII CACE file
 	and <filename_out> is the name of the file to write.
@@ -154,33 +169,22 @@ $ make editable
 
 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.
 
-(NOTE:  Example repositories, like CACE itself, are currently a work in progress.)
+> [!NOTE]
+> Example repositories, like CACE itself, are currently a work in progress.
 
 All repositories are rooted at: [https://github.com/RTimothyEdwards/](https://github.com/RTimothyEdwards/).
 
 Example circuit repositories:
 
-	sky130_ef_ip__instramp		Instrumentation amplifier
-	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
+- [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.
-
-## Documentation
-
-To build the documentation, run:
-
-	$ make docs
-
-Th host the docs, run:
-
-	$ make host-docs
-
-Note: The documentation is not yet hosted online anywhere.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,6 +1,8 @@
 Welcome to CACE's documentation!
 ================================
 
+Please note that this documentation is still a work in progress.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:

diff --git a/docs/source/usage/getting_started.md b/docs/source/usage/getting_started.md
@@ -2,9 +2,49 @@
 
 ## Installation
 
-For now, CACE can be manually installed using pip.
+You'll need the following:
 
-First the Python package needs to be build:
+- 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)
+
+## 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).
+
+To install the dependencies for CACE, run:
+
+	$ make dependencies
+
+### Python Package
+
+To build the Python package, run:
 
 ```
 $ make build
@@ -16,33 +56,32 @@ To install the package, run:
 $ make install
 ```
 
-CACE is currently a work in progress and does not have an
-installer;  it may be run directly from the source repository
-clone.  Future work will allow CACE to be installed with the
-standard python "pip" installer or a Makefile install target,
-and run from the command line simply as "cace".
+To install the package in editable mode, run:
 
-## Usage
+```
+$ make editable
+```
+
+### Documentation
 
-If installed properly as Python package, CACE can be started from the command line using:
+To build the documentation, run:
 
 ```
-$ cace
+$ make docs
 ```
 
-Or to start the GUI:
+To host the docs, run:
 
 ```
-$ cace-gui
+make host-docs
 ```
 
+> [!NOTE]  
+> The documentation can be viewed online at [cace.readthedocs.io](https://cace.readthedocs.io/). 
 
-The `cace_gui.py` script is a top-level GUI for the CACE system. The CACE system can also be run manually as `cace_cli.py`. For
-interactive usage information for the command line, run `cace-cli.py` without any arguments.
-
-CACE GUI syntax:
+## CACE GUI syntax
 
-	/path/to/cace_gui.py [path/to/project.txt]
+    $ cace-gui [path/to/project.txt]
 
 	where optional file project.txt (normally <name_of_project>.txt
 	where <name_of_project> is the name of the circuit to be
@@ -63,9 +102,9 @@ CACE GUI syntax:
 	standalone circuits, or a project may simply be a collection of
 	circuits (library) without a specific single top level. 
 
-CACE command line syntax:
+## CACE command line syntax
 
-	/path/to/cace.py <filename_in> <filename_out> [options]
+	$ cace <filename_in> <filename_out> [options]
 
 	where <filename_in> is a format 4.0 ASCII CACE file
 	and <filename_out> is the name of the file to write.
@@ -110,4 +149,27 @@ CACE command line syntax:
 	Option "-nosim" does not re-run simulations if the output file exists.
 	   (Warning---does not check if simulations are out of date).
 
-	Option "-summary" prints a summary of results at the end.
+	Option "-summary" prints a summary of results at the end.
+
+## 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.
+
+(NOTE:  Example repositories, like CACE itself, are currently a work in progress.)
+
+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.