Update Documentation (The-OpenROAD-Project#1917)

+ Added `make docs` target to primary Makefile to generate documentation ~ Update documentation dependencies ~ Updated `tcl.py` to handle JSON lists of elements including whitespace by joining them with a comma (unless one of the elements already contains a comma), resolving odd JSON syntax ~ Re-organized and re-order configuration variables and edited descriptions for general consistency as well as adding anchors ~ Update all documentation dependencies ~ Fixed a number of broken links - Remove dependency on `docutils` and `sphinx-autobuild` (both unused) - Remove two of the custom documentation extensions
MrShaTr · Jul 25, 2023 · 157a650 · 157a650
1 parent f6e50ab
commit 157a650
Show file tree

Hide file tree

Showing 18 changed files with 500 additions and 661 deletions.
diff --git a/.github/scripts/variables_documentation.py b/.github/scripts/variables_documentation.py
@@ -158,14 +158,15 @@
     subprocess.check_output(
         [
             "rg",
-            "\\| *`([A-Z]\\S+) *` *‡*  *\\|",
+            r"^\s*\|\s*`([A-Z_]+)`",
             "-r",
             "$1",
             "-o",
             "-N",
             "-I",
             "--no-ignore",
-            "docs",
+            "docs/source/reference/configuration.md",
+            "docs/source/reference/pdk_configuration.md",
         ]
     )
     .decode("utf-8")
@@ -174,32 +175,31 @@
 docs_variables = [var for var in docs_variables if var.isupper()]
 docs_variables_set = set(docs_variables)
 
-deprecated_docs_variables = (
+used_variables = (
     subprocess.check_output(
         [
             "rg",
-            "\\| *`([A-Z]\\S+) *` *‡*  *\\|.*(Deprecated|Removed)",
+            r"\$::env\(\s*([A-Z_]+?)\s*\)",
             "-r",
             "$1",
             "-o",
             "-N",
             "-I",
             "--no-ignore",
-            "docs",
+            "scripts",
+            "flow.tcl",
         ]
     )
     .decode("utf-8")
     .split()
 )
-depreacted_docs_variables = [var for var in deprecated_docs_variables if var.isupper()]
-deprecated_docs_variables_set = set(deprecated_docs_variables)
-
+used_variables_set = set(used_variables)
 
-used_variables = (
+translated_deprecated_variables = (
     subprocess.check_output(
         [
             "rg",
-            "\\$::env\\(([A-Z]\\S+?)\\)",
+            r"handle_deprecated_config\s+([A-Z_]+)",
             "-r",
             "$1",
             "-o",
@@ -213,15 +213,18 @@
     .decode("utf-8")
     .split()
 )
-used_variables_set = set(used_variables)
+translated_deprecated_variables_set = set(translated_deprecated_variables)
 
-undocumented = sorted(
-    used_variables_set - docs_variables_set - deprecated_docs_variables_set - white_list
-)
+undocumented = sorted(used_variables_set - docs_variables_set - white_list)
 if undocumented:
     print("[ERROR]: found the following undocumented variables.")
     for var in undocumented:
         print(var)
     exit(1)
 else:
     print("Pass")
+
+# unused = sorted(
+#     docs_variables_set - used_variables_set - translated_deprecated_variables_set
+# )
+# print(unused)
diff --git a/Makefile b/Makefile
@@ -137,6 +137,11 @@ lint: venv/created
 	./venv/bin/black --check .
 	./venv/bin/flake8 .
 
+.PHONY: docs
+docs: venv/created
+	$(MAKE) -C docs install
+	$(MAKE) -C docs html
+
 .PHONY: start-build-env
 start-build-env: venv/created
 	bash -c "bash --rcfile <(cat ~/.bashrc ./venv/bin/activate)"

diff --git a/configuration/general.tcl b/configuration/general.tcl
@@ -39,7 +39,6 @@ set ::env(USE_ARC_ANTENNA_CHECK) 1
 set ::env(RUN_SPEF_EXTRACTION) 1
 set ::env(RUN_IRDROP_REPORT) 1
 
-
 ## Signoff
 set ::env(RUN_CVC) 1
 set ::env(PRIMARY_SIGNOFF_TOOL) magic
@@ -72,8 +71,6 @@ set ::env(MAGIC_GDS_POLYGON_SUBCELLS) 0
 ### Klayout-Specific
 set ::env(RUN_KLAYOUT) 1
 set ::env(RUN_KLAYOUT_DRC) 0
-set ::env(KLAYOUT_XOR_GDS) 1
-set ::env(KLAYOUT_XOR_XML) 1
 set ::env(KLAYOUT_XOR_THREADS) 1
 set ::env(KLAYOUT_XOR_IGNORE_LAYERS) ""
 set ::env(TAKE_LAYOUT_SCROT) 0

diff --git a/docs/_ext/markdown_code_links.py b/docs/_ext/markdown_code_links.py
diff --git a/docs/_ext/markdown_cross_doc_section_links.py b/docs/_ext/markdown_cross_doc_section_links.py
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,5 +1,3 @@
-furo==2022.6.21
-docutils==0.17
-sphinx==4.5.0
-sphinx-autobuild==2021.3.14
-myst-parser==0.18.0
+furo==2023.5.20 
+sphinx>=7,<8
+myst-parser>=2,<3
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -39,8 +39,6 @@
 # ones.
 extensions = [
     "sphinx.ext.todo",
-    "markdown_code_links",  # CUSTOM
-    "markdown_cross_doc_section_links",  # CUSTOM
     "sphinx.ext.autosectionlabel",
     "image_links",  # CUSTOM
     "myst_parser",
@@ -107,29 +105,15 @@
 
 todo_include_todos = True
 numfig = True
-
-markdown_code_links_githubrepo = repo
-markdown_code_links_githubbranch = f"blob/{branch}"
-markdown_code_links_codefileextensions = [
-    ".tcl",
-    ".sh",
-    ".cfg",
-    ".gds",
-    ".sdc",
-    "/",
-    ".json",
-    "Makefile",
-]
 autosectionlabel_prefix_document = True
 
 suppress_warnings = ["misc.highlighting_failure"]  # supress json highlight warnings
 
 myst_heading_anchors = 3
 
-
 myst_enable_extensions = [
     "colon_fence",
+    "attrs_block",
 ]
 
-
 root_doc = "index"
diff --git a/docs/source/getting_started/quickstart.md b/docs/source/getting_started/quickstart.md
@@ -11,7 +11,7 @@ This guide covers running the flow on existing desings, adding new designs and q
 ## Starting the OpenLane Environment
 
 :::{note}
-If you installed OpenLane following [local installation](installation_local.md) steps, these instructions will not entirely apply. We no longer actively support local installation.
+If you installed OpenLane following [local installation](installation/installation_local.md) steps, these instructions will not entirely apply. We no longer actively support local installation.
 :::
 
 OpenLane uses Docker to create a reproducible environment for your projects. You don't need any extra steps to run the Docker image, as the Makefile already takes care of it. Just run the following commands to enter the OpenLane environment: