Theme change for docs to fix header linking issue (#1131)

* changed theme, added docs build folder to gitignore
* Fixed missing link in GettingInvolved
* update faqs
* removed commented code
* update search tips and admonitions
* added link to git quickstart, using wget
* add comments for conf.py

Signed-off-by: luarss <[email protected]>
Signed-off-by: Vitor Bandeira <[email protected]>
Co-authored-by: Vitor Bandeira <[email protected]>

Author: luarss

.gitignore

@@ -84,5 +84,7 @@ dependencies/
 perf.data
 perf.data.old
 
+# documentation specific
 docs/main
 docs/build
+GitGuide.md

docs/conf.py

@@ -13,6 +13,7 @@
 import docutils
 import os
 import re
+import requests
 
 # -- Project information -----------------------------------------------------
 
@@ -33,6 +34,7 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.todo',
     'sphinx_external_toc',
+    'sphinx_copybutton',
     'myst_parser',
 ]
 
@@ -87,62 +89,54 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_symbiflow_theme"
+html_theme = "sphinx_book_theme"
 
 html_theme_options = {
-    # Repository integration
-    # Set the repo url for the link to appear
-    'github_url': 'https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts',
-    # The name of the repo. If must be set if github_url is set
-    'repo_name': 'OpenROAD Flow',
-    # Must be one of github, gitlab or bitbucket
-    'repo_type': 'github',
-
-    # Set the name to appear in the left sidebar/header. If not provided, uses
-    # html_short_title if defined, or html_title
-    'nav_title': "OpenROAD Flow",
-
-    # A list of dictionaries where each has three keys:
-    #   href: The URL or pagename (str)
-    #   title: The title to appear (str)
-    #   internal: Flag indicating to use pathto (bool)
-    'nav_links': [
-        {"title": "Home", "href": "index", "internal": True},
-        {"title": "The OpenROAD Project", "href": "https://theopenroadproject.org", "internal": False},
-    ],
-
-    # Customize css colors.
-    # For details see link.
-    # https://getmdl.io/customize/index.html
-    #
-    # Primary colors:
-    # red, pink, purple, deep-purple, indigo, blue, light-blue, cyan,
-    # teal, green, light-green, lime, yellow, amber, orange, deep-orange,
-    # brown, grey, blue-grey, white
-    # (Default: deep-purple)
-    'color_primary': 'indigo',
-    # Values: Same as color_primary. 
-    #(Default: indigo)
-    'color_accent': 'blue',
-
-    # Hide the symbiflow links
-    'hide_symbiflow_links': True,
-
-    "html_minify": False,
-    "html_prettify": True,
-    "css_minify": True,
-    "globaltoc_depth": 2,
-    "table_classes": ["plain"],
-    "master_doc": False,
+    "repository_url": "https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts",
+    "repository_branch": "master",
+    "use_download_button": True,
+
+    # list for more fine-grained ordering of icons
+    "icon_links": [
+        {
+            "name": "The OpenROAD Project",
+            "url": "https://theopenroadproject.org/",
+            "icon": "fa-solid fa-globe",
+        },
+        {
+            "name": "Twitter",
+            "url": "https://twitter.com/OpenROAD_EDA",
+            "icon": "fa-brands fa-twitter",
+        },
+        {
+            "name": "Email",
+            "url": "mailto:[email protected]",
+            "icon": "fa-solid fa-envelope",
+        },
+        {
+            "name": "GitHub",
+            "url": "https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "Stars",
+            "url": "https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts/stargazers",
+            "icon": "https://img.shields.io/github/stars/The-OpenROAD-Project/OpenROAD-flow-scripts",
+            "type": "url",
+        },
+   ],
 }
 
 # 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".
-# html_static_path = ['_static']
+
+def get_file_from_url(url, fname):
+    r = requests.get(url)
+    with open(fname, 'wb') as f:
+        f.write(r.content)
 
 def setup(app):
-    import os
     if not os.path.exists('main'):
         os.symlink('..', 'main')
     prefix = '(../'
@@ -152,3 +146,16 @@ def setup(app):
     lines = lines.replace(prefix, newPath)
     with open('index.md', 'wt') as f:
         f.write(lines)
+
+    url = 'https://raw.githubusercontent.com/The-OpenROAD-Project/OpenROAD/master/docs/contrib/GitGuide.md'
+    get_file_from_url(url, 'contrib/GitGuide.md') 
+
+    # edit OpenROAD to OpenROAD-flow-scripts for GitGuide
+    with open('contrib/GitGuide.md', 'r') as f:
+        content = f.read()
+
+    content = content.replace('user/Build.md', '../index.md#build-or-installing-orfs-dependencies')
+    content = content.replace('OpenROAD', 'OpenROAD-flow-scripts')
+    content = content.replace('The-OpenROAD-flow-scripts', 'The-OpenROAD')
+    with open('contrib/GitGuide.md', 'w') as f:
+        f.write(content)

docs/contrib/CI.md

@@ -21,12 +21,10 @@ navigate Jenkins to access these features are available
 
 -   OpenROAD-flow-script-Public [folder]
     -   `public_tests_all`
-        -   Description: runs flow tests except RTLMP designs. Should finish in
-            less than three hours.
+        -   Description: runs flow tests that finish in less than three hours.
         -   Target: master branch.
     -   `public_tests_all-pr`
-        -   Description: runs flow tests except RTLMP designs. Should finish in
-            less than three hours.
+        -   Description: runs flow tests that finish in less than three hours.
         -   Target: all open PRs.
     -   `publish-results-to-dashboard`
         -   Description: uploads metrics to dashboard website.
@@ -36,10 +34,9 @@ navigate Jenkins to access these features are available
     -   Target: master branch.
 -   OpenROAD-flow-scripts-Private [folder]
     -   `public_tests_small`
-        -   Description: runs fast flow tests, does not include RTLMP designs.
-            Should finish in less than one hour.
+        -   Description: runs fast flow tests that finish in less than one hour.
         -   Target: all branches that are not filed as PR. CI will run for PR
             branches on the public side after "Ready to Sync Public" workflow.
 -   OpenROAD-flow-scripts-All-Tests-Private
-    -   Description: runs flow tests, does not include RTLMP designs.
-    -   Target: secure branches.
+    -   Description: runs flow tests for private branches.
+    -   Target: secure branches.

docs/contrib/CODE_OF_CONDUCT.md

@@ -114,15 +114,9 @@ the community.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+This Code of Conduct is adapted from the [Contributor Covenant version 2.0](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html).
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/inclusion).
 
-[homepage]: https://www.contributor-covenant.org
-
-For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
+For answers to common questions about this code of conduct, see the FAQ [here](https://www.contributor-covenant.org/faq). Translations are available [here](https://www.contributor-covenant.org/translations).

docs/contrib/DeveloperGuide.md

@@ -4,3 +4,4 @@
 - Adding a new design: [Guide](../user/AddingNewDesign.md).
 - Continuous Integration: [Guide](./CI.md).
 - How do I update the codebase? There are different ways to update your codebase depending on the method you installed it. We provide detailed instructions in this [guide](../user/FAQS.md).
+- How do I contribute? Follow our Git Quickstart guide [here](./GitGuide.md).

docs/contrib/GettingInvolved.md

@@ -41,7 +41,7 @@ If you find code in our project that does *not* follow this guide, then within e
 you edit, follow the style in that file.
 
 Please pay careful attention to the
-[tool checklist](DeveloperGuide.md#Tool Checklist) for all code. If you want
+[tool checklist](https://openroad.readthedocs.io/en/latest/contrib/DeveloperGuide.html#tool-checklist) for all code. If you want
 to add or improve functionality in OpenROAD, please start with the
 top-level [app](https://github.com/The-OpenROAD-Project/OpenROAD/) repo. You
 can see in the `src` directory that submodules exist pointing to tested

docs/contrib/PlatformBringUp.md

@@ -7,7 +7,7 @@ easily integrate and test a new technology in to the OpenROAD RTL to GDS
 flow. OpenROAD allows you to integrate any PDK (Process Design Kit) for any
 feature size and implement a fully open-sourced RTL-GDSII flow (synthesizable
 Verilog to merged GDSII). The OpenROAD flow has been validated for feature
-sizes down to 7nm and used to design and tapeout over 100 ASIC and SoCs
+sizes down to 7nm and used to design and tapeout over 600 ASIC and SoCs
 to date.
 
 ## Prerequisites
@@ -58,7 +58,7 @@ each other unless otherwise stated.
 Make the following edits  to the Makefile (located in `flow/Makefile`)
 so that OpenROAD can run the flow on a design using the new platform.
 
-At  the beginning of the Makefile, there is a block of `DESIGN_CONFIG`
+At the beginning of the Makefile, there is a block of `DESIGN_CONFIG`
 variables that are commented out. These variables tell OpenROAD which
 design to run and on what platform. `DESIGN_CONFIG` specifically points
 to a `config.mk` file located in the designs directory for the respective
@@ -70,8 +70,8 @@ already made which can be used with any platform (see `flow/designs/src`
 for a list of usable designs). For example, a `DESIGN_CONFIG` variable
 using the `gcd` design on a new platform would look as follows:
 
-```
-#Makefile
+```{code-block} Makefile
+:caption: Makefile
 DESIGN_CONFIG=./designs/MyNewPlatform/gcd/config.mk
 ```
 
@@ -83,8 +83,8 @@ Directory](content:design:directory) section of this document.
 Create a directory for the new technology inside `flow/platforms` to contain
 the necessary files for the OpenROAD flow.
 
-```
-$ mkdir flow/platforms/MyNewPlatform
+``` shell
+mkdir flow/platforms/MyNewPlatform
 ```
 (content:design:directory)=
 ### Design Directory
@@ -95,17 +95,18 @@ to contain the relevant files and directories for all the designs for the
 flow in that specific platform. Each design requires its own `config.mk`
 and `constraint.sdc` files.
 
+:::{tip}
 Follow the steps below to create the necessary directories and files.
-**NOTE: gcd is just an example and not a required name.**:
+Note gcd is just an example and not a required name.
 
+``` shell
+mkdir -p flow/designs/MyNewPlatform/gcd
+touch flow/designs/MyNewPlatform/gcd/config.mk
+touch flow/designs/MyNewPlatform/gcd/constraint.sdc
 ```
-$ mkdir -p flow/designs/MyNewPlatform/gcd
-$ touch flow/designs/MyNewPlatform/gcd/config.mk
-$ touch flow/designs/MyNewPlatform/gcd/constraint.sdc
-```
-
 This creates two directories MyNewPlatform and `gcd` and two empty files
 `config.mk` and `constraint.sdc` in `flow/designs/MyNewPlatform/gcd`.
+:::
 
 ### Platform Configuration
 
@@ -147,9 +148,8 @@ descriptor of all variables see [here](../user/FlowVariables.md).
 
 Following is a sample `config.mk` file for the `gcd` design:
 
-```
-#config.mk
-###########################
+```{code-block} shell
+:caption: config.mk
 export DESIGN_NAME     = gcd
 export PLATFORM        = sky130hd
 
@@ -172,9 +172,8 @@ need to be consistent with the liberty time units. Here’s an example of
 a `constraint.sdc` file which defines a clock `clk` with a period of 8.4
 nanoseconds (nanoseconds being consistent with the liberty time units).
 
-```
-#constraint.sdc
-############################
+```{code-block} tcl
+:caption: constraint.sdc
 create_clock [get_ports clk] -period 8.4  #Units are in nanoseconds
 ```
 
@@ -191,10 +190,10 @@ have all relevant files in one localized directory. The `.lib`, `.lef`, and
 `.gds` reside in directories named respectively for the specific technology.
 
 For example:
-```
-$ mdkir flow/platforms/MyNewPlatform/lib
-$ mdkir flow/platforms/MyNewPlatform/lef
-$ mdkir flow/platforms/MyNewPlatform/gds
+``` shell
+mdkir flow/platforms/MyNewPlatform/lib
+mdkir flow/platforms/MyNewPlatform/lef
+mdkir flow/platforms/MyNewPlatform/gds
 ```
 
 A merged GDS file may be used instead of adding every individual `.gds`
@@ -218,9 +217,8 @@ design.
 To create this module, a gated clock standard cell is required. This standard
 cell is used to create the generic module `OPENROAD_CLKGATE`, as shown below.
 
-```
-// cells_clkgate.v
-//////////////////////////
+```{code-block} verilog
+:caption: cells_clkgate.v
 module OPENROAD_CLKGATE (CK, E, GCK);
   input  CK;
   input  E;
@@ -232,10 +230,9 @@ endmodule
 
 An example instantiation of this module in a user design is shown below.
 
-```
-// buffer.v
+```{code-block} verilog
+:caption: buffer.v
 // This is not a platform file, this is an example user design
-//////////////////////////
 
 module buffer (clk, enable, in, out);
 
@@ -267,9 +264,8 @@ level-sensitive latch.
 
 This file is only required if you want to infer latches for your design.
 
-```
-// cells_latch.v
-//////////////////////////
+```{code-block} verilog
+:caption: cells_latch.v
 module $_DLATCH_P_(input E, input D, output Q);
   <d_latch_std_cell> _TECHMAP_REPLACE_ (
     .D (D),
@@ -295,11 +291,9 @@ layer resources, set which routing heuristic to use when routing, etc. It’s
 recommended to use the default `fastroute.tcl` due to its simplicity and
 effectiveness. Following is the default FastRoute configuration file.
 
-```
-# fastroute.tcl
-#####################
+```{code-block} tcl
+:caption: fastroute.tcl
 set_global_routing_layer_adjustment $::env(MIN_ROUTING_LAYER)-$::env(MAX_ROUTING_LAYER) 0.5
-
 set_routing_layers -signal $::env(MIN_ROUTING_LAYER)-$::env(MAX_ROUTING_LAYER)
 ```
 
@@ -323,9 +317,8 @@ to the `LAYER` definition section for each metal in the tech LEF. Following
 is a generalized metal tracks configuration file with five metal tracks
 defined. **Units are in microns**.
 
-```
-# make_tracks.tcl
-###############################
+```{code-block} tcl
+:caption: make_tracks.tcl
 make_tracks metal1 -x_offset 0.24 -x_pitch 0.82 -y_offset 0.24 -y_pitch 0.82
 make_tracks metal2 -x_offset 0.28 -x_pitch 0.82 -y_offset 0.28 -y_pitch 0.82
 make_tracks metal3 -x_offset 0.28 -x_pitch 0.82 -y_offset 0.28 -y_pitch 0.82
@@ -334,8 +327,7 @@ make_tracks metal5 -x_offset 0.28 -x_pitch 0.82 -y_offset 0.28 -y_pitch 0.82
 ```
 
 Following is the `LAYER` definition for `metal1` in the `sky130hd` tech LEF.
-
-```
+``` 
 LAYER met1
   TYPE ROUTING ;
   DIRECTION HORIZONTAL ;
@@ -397,9 +389,8 @@ values. Often, per-unit-length values are available in the PDK user guide. For
 of a `setRC` configuration file which sets the resistance and capacitance
 of five metal layers, four vias, one signal wire, and one clock wire.
 
-```
-# setRC.tcl
-#######################
+```{code-block} tcl
+:caption: setRC.tcl
 set_layer_rc -layer M1 -capacitance 1.449e-04 -resistance 8.929e-04
 set_layer_rc -layer M2 -capacitance 1.331e-04 -resistance 8.929e-04
 set_layer_rc -layer M3 -capacitance 1.464e-04 -resistance 1.567e-04