Merge branch 'master' into mb@update

Signed-off-by: louiic <[email protected]>

Author: louiic

.gitignore

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

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.7"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt

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',
 ]
 
@@ -57,8 +59,6 @@
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
 source_suffix = ['.md']
 
 # The master toctree document.
@@ -87,62 +87,58 @@
 # 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",
+    "show_navbar_depth": 2,
+    "use_edit_page_button": True,
+    "use_source_button": True,
+    "use_issues_button": True,
+    "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 +148,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