Installation, Quickstart Guide and Sphynx Overhaul (The-OpenROAD-Proj…

…ect#1259) + Documentation changed, README no longer documentation's landing page + New installation and quickstart guides created
MrShaTr · Sep 6, 2022 · 826bb8f · 826bb8f
1 parent d5cd97d
commit 826bb8f
Show file tree

Hide file tree

Showing 30 changed files with 772 additions and 192 deletions.
diff --git a/.github/workflow-documentation.md b/.github/workflow-documentation.md
@@ -1,21 +1,21 @@
-# Openlane CI/CD
+# For developers: CI/CD
 There are two primary flows: the pull request flow and the deployment flow.
 
 The deployment flow occurs on a daily basis. The PR flow happens whenever someone creates a new Pull Request. PRs can be created by contributors or by an automated tool updater that runs on a schedule.
 
 ![A Diagram Of The Flow](./diagrams/flow.png)
 * A maintainer cannot review their own code, but they can merge it after a review by another maintainer.
 
-# Required Secrets
+## Required Secrets
 Repository secrets are used to protect certain credentials, but also as repository-dependent parameters for the CI.
 
-## Common
+### Common
 | Secret      | Description                                                   |
 |---------------|---------------------------------------------------------------|
 | `MAIN_BRANCH`  | The main branch for OpenLane. Format: `main`|`master`|`etc` |
 | `MY_TOKEN`  | A token for a bot account that: 1. owns the fork for the tool update. 2. has write access to the volare repo to push newly-built PDKs to. |
 
-## CI
+### CI
 
 | Secret      | Description                                                   |
 |---------------|---------------------------------------------------------------|
@@ -25,7 +25,7 @@ Repository secrets are used to protect certain credentials, but also as reposito
 | `DOCKERHUB_PASSWORD`  | The password/token for the given username that has push access to the organization that owns `DOCKER_IMAGE` on Docker Hub. |
 | `VOLARE_OWNER`/`VOLARE_REPO` | (optional) A volare repo to cache builds in. In our case, `VOLARE_OWNER` would be `efabless` and `VOLARE_REPO` would be `volare`. |
 
-## Tool Updater
+### Tool Updater
 
 | Secret      | Description                                                   |
 |---------------|---------------------------------------------------------------|

diff --git a/AUTHORS.md b/AUTHORS.md
@@ -1,3 +1,4 @@
+# Authors
 Efabless Corporation is the principal author of this software for the purpose
 of copyright. All binaries provided are also distributed by Efabless Corporation.
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,10 +1,10 @@
 # How to Contribute
 We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow.
 
-# Branching
+## Branching
 For various reasons, it's recommended to call working branches, even in your forks, something else other than `master` or `main`, as those two branch names do have some special behavior associated with them. 
 
-# Testing and Code Standards
+## Testing and Code Standards
 Before you submit your changes, it's prudent to perform some kind of smoke test. `make test` tests a simple spm design to ensure nothing has gone horribly wrong.
 
 ## Choice of Language
@@ -35,18 +35,18 @@ There are some special guidelines for scripts in `scripts/yosys`, `scripts/openr
     * $DESIGN_DIR
 
 
-# Submissions
+## Submissions
 Make your changes and then submit them as a pull requests to the `master` branch.
 
 Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more information on using pull requests.
 
-## The Approval Process
+### The Approval Process
 For a PR to be merged, there are two requirements:
 
 - There are two automated checks, one for linting and the other for functionality. Both must pass.
 - An OpenLane team member must inspect and approve the PR.
 
-# Licensing and Copyright
+## Licensing and Copyright
 Please add you (or your employer's) copyright headers to any files to which you have made major edits.
 
 Please note all code contributions must have the same license as OpenLane, i.e., the Apache License, version 2.0. 
diff --git a/conf.py b/conf.py
@@ -41,12 +41,9 @@
     "markdown_cross_doc_section_links",  # CUSTOM
     "sphinx.ext.autosectionlabel",
     "image_links",  # CUSTOM
-    "toc_from_markdown",  # CUSTOM
     "myst_parser",
 ]
 
-# Expand source suffixes
-
 source_suffix = {
     ".rst": "restructuredtext",
     ".md": "markdown",
@@ -111,6 +108,4 @@
 myst_heading_anchors = 3
 
 
-def setup(app):
-    app.emit("create_index_softlink", "README.md", True)
-    app.emit("toc_from_markdown", "README.md", ".autotoc.rst", True)
+root_doc = "index"
diff --git a/docker/README.md b/docker/README.md
@@ -1,4 +1,4 @@
-# The OpenLane Docker Image
+# For developers: Building the Docker Image
 Note: You probably shouldn't be here.
 
 ## Structure

diff --git a/docs/Makefile b/docs/Makefile
@@ -16,18 +16,23 @@
 # Minimal makefile for Sphinx documentation
 #
 
+export SHELL=/bin/bash
+
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
+SPHINXBUILD   ?= source ../venv/bin/activate && sphinx-build
 SOURCEDIR     = ..
 BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile install
+
+install:
+	source ../venv/bin/activate && python -m pip install -r requirements.txt 
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

diff --git a/docs/_ext/toc_from_markdown.py b/docs/_ext/toc_from_markdown.py
diff --git a/docs/_static/docs_contribution/code_block_issue.png b/docs/_static/docs_contribution/code_block_issue.png
diff --git a/docs/_static/docs_contribution/code_block_spaces_around_the_code.png b/docs/_static/docs_contribution/code_block_spaces_around_the_code.png
diff --git a/docs/_static/docs_contribution/code_block_supposed_look.png b/docs/_static/docs_contribution/code_block_supposed_look.png
diff --git a/docs/_static/installation/spm.png b/docs/_static/installation/spm.png
diff --git a/docs/source/chip_integration.md b/docs/source/chip_integration.md
@@ -1,7 +1,7 @@
 **THIS PAGE IS STILL UNDER DEVELOPMENT.**
 **THE INFORMATION HERE MIGHT BE PARTIALLY INCORRECT OR OUTDATED.**
 
-# Chip Integration
+# Chip Level Integration
 
 Using openlane, you can produce a GDSII from a chip RTL.
 
@@ -131,7 +131,7 @@ When you use the `power_routing` command in the chip interactive script, the pow
 
 [This][1] has a description for all OpenLane commands.
 
-[0]: ./../../configuration/README.md
+[0]: ./configuration.md
 [1]: ./openlane_commands.md
 [2]: ./advanced_readme.md
 [3]: https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/pdn/doc/PDN.md
@@ -140,6 +140,6 @@ When you use the `power_routing` command in the chip interactive script, the pow
 [6]: https://github.com/efabless/caravel/blob/mpw-one-b/openlane/chip_io/padframe.cfg
 [7]: ./../../scripts/topModuleGen/README.md
 [8]: ./hardening_macros.md
-[9]: https://github.com/efabless/openlane/tree/master/designs/manual_macro_placement_test
+[9]: https://github.com/The-OpenROAD-Project/openlane/tree/master/designs/manual_macro_placement_test
 [10]: ./advanced_power_grid_control.md
 [11]: https://github.com/efabless/caravel/blob/mpw-one-b/openlane/caravel/interactive.lvs.tcl
diff --git a/configuration/README.md → docs/source/configuration.md b/configuration/README.md → docs/source/configuration.md
@@ -287,4 +287,4 @@ These variables worked initially, but they were too sky130 specific and will be
 | `QUIT_ON_LVS_ERROR` | Checks for LVS errors after netgen LVS is executed and exits the flow if any was found. 1 = Enabled, 0 = Disabled <br> (Default: `1`)|
 
 
-[0]: ./../designs/spm/pin_order.cfg
+[0]: ./../../../designs/spm/pin_order.cfg
Original file line number	Diff line number	Diff line change
Expand Up		@@ -287,4 +287,4 @@ These variables worked initially, but they were too sky130 specific and will be
		\| `QUIT_ON_LVS_ERROR` \| Checks for LVS errors after netgen LVS is executed and exits the flow if any was found. 1 = Enabled, 0 = Disabled <br> (Default: `1`)\|


		[0]: ./../designs/spm/pin_order.cfg
		[0]: ./../../../designs/spm/pin_order.cfg