docs: vendor OpenROAD sources instead of fetching master

.gitattributes

@@ -1,3 +1,9 @@
 # Make Github ignore the designs folder when determining repo language
 flow/designs/src/* linguist-vendored
 flow/scripts/variables.json linguist-generated=true
+
+# Byte-for-byte copies of OpenROAD files, regenerated by
+# docs/scripts/refresh_openroad_docs.py. Upstream's trailing whitespace must
+# survive verbatim, or the refresh is no longer idempotent and the vendored
+# copies stop matching the commit SOURCE.json pins.
+docs/_vendor/openroad/** -whitespace

.github/workflows/github-actions-cron-update-OR.yml

@@ -22,6 +22,13 @@ jobs:
           echo "::set-output name=has_update::$(git --no-pager diff --name-only origin/master..HEAD)"
           git checkout master
           git pull
+      - name: Refresh vendored OpenROAD docs
+        # docs/conf.py reads docs/_vendor/openroad/ instead of downloading from
+        # GitHub while Sphinx runs, so the vendored copies must be re-taken at
+        # the new submodule SHA. Running it here puts the docs refresh in the
+        # same commit as the submodule bump, which is what
+        # docs/scripts/check_vendored_docs.py asserts.
+        run: python3 docs/scripts/refresh_openroad_docs.py
       - if: "steps.remote-update.outputs.has_update != ''"
         name: Create Draft PR
         uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1  # v8.1.1

.gitignore

@@ -85,12 +85,15 @@ perf.data
 perf.data.old
 
 # documentation specific
+# Everything below is generated by docs/conf.py during `make html`; the sources
+# are docs/index.md, ../README.md and docs/_vendor/openroad/ (see
+# docs/_vendor/openroad/README.md).
 docs/main
 docs/build
-SupportedOS.md
 index2.md
 Manpage.md
 mainREADME.md
+docs/contrib/GitGuide.md
 build
 .scala-build/
 .bsp/
@@ -107,4 +110,5 @@ MODULE.bazel.lock
 
 # python venv
 venv/
+.venv/
 tmp/

.readthedocs.yaml

@@ -8,7 +8,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: "3.12"
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

docs/Makefile

@@ -7,12 +7,20 @@ SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     =
 BUILDDIR      = build
+# Read the Docs builds with 3.12 (see .readthedocs.yaml); override if you want
+# a specific interpreter locally.
+PYTHON        ?= python3
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+# Create a local virtualenv and install the hash-pinned doc-build dependencies.
+venv:
+	$(PYTHON) -m venv .venv
+	.venv/bin/pip install -r requirements_lock.txt
+
+.PHONY: help Makefile venv
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/README.md

@@ -11,28 +11,33 @@ repository and is published at
 
 ### Requires
 
-- Python 3.10 — the version Read the Docs builds with (see `.readthedocs.yaml`).
-  The pinned Sphinx release does not run on Python 3.13 or newer.
+- Python 3.10+ (tested through 3.14) — Read the Docs builds with 3.12 (see
+  `.readthedocs.yaml`); any recent `python3` on PATH works locally.
 - `pip`
 - `virtualenv` (or the standard-library `venv`)
 
 ### Install prerequisites
 
-Run from the repository root:
+Run from `docs/`:
 
 ``` shell
-virtualenv .venv
+make venv
 source .venv/bin/activate
-pip install -r docs/requirements_lock.txt
 ```
 
+`make venv` just runs `python3 -m venv .venv && .venv/bin/pip install -r
+requirements_lock.txt`; pass `PYTHON=/path/to/python3` to use a specific
+interpreter instead of whatever `python3` resolves to on your PATH.
+
 `docs/requirements_lock.txt` is the hash-pinned lock file that Read the Docs
 installs, so a local build matches the published one. The direct dependencies
 are listed in `docs/requirements.in`; after editing that file, regenerate the
-lock with:
+lock with [`uv`](https://docs.astral.sh/uv/) (`pip-compile` from `pip-tools`
+is a documented alternative, but at time of writing has a compatibility bug
+with recent `pip` releases):
 
 ``` shell
-pip-compile --generate-hashes --output-file=docs/requirements_lock.txt docs/requirements.in
+uv pip compile --upgrade --generate-hashes --output-file=docs/requirements_lock.txt docs/requirements.in
 ```
 
 ### Build
@@ -62,7 +67,7 @@ It exits non-zero when any link is unreachable.
   `SupportedOS.md`, `Manpage.md`, `mainREADME.md`, and — because it is fetched
   rather than authored here — the tracked file `contrib/GitGuide.md`. Do not
   commit those changes; `git checkout docs/contrib/GitGuide.md` after a build.
-- Always `rm -rf docs/build` before rebuilding. The output directory is
-  `build/`, but `conf.py`'s `exclude_patterns` only excludes `_build`, so a
-  second run picks up the Markdown files written under `build/html/` as if they
-  were source pages.
+- `conf.py`'s `exclude_patterns` excludes `build` (the actual output directory
+  — Sphinx's own default is `_build`) and any local `.venv`/`venv`, so re-running
+  a build, or building from a checkout with a local virtualenv already in
+  `docs/`, does not pick that up as source content.

docs/_vendor/openroad/GitGuide.md

@@ -0,0 +1,207 @@
+# Git Quickstart
+
+This tutorial serves as a quickstart to Git and contributing to our repository. If you have not already set up OpenROAD, please follow the instructions [here](../user/Build.md). 
+
+```{tip} This basic tutorial gives instruction for basic password Git authentication.
+If you would like to setup SSH authentication, please follow this [guide](https://help.github.com/set-up-git-redirect).
+```
+
+## Forking
+
+You will need your own fork to work on the code. Go to the `OpenROAD` project
+[page](https://github.com/The-OpenROAD-Project/OpenROAD) and hit the `Fork` button. You will
+want to clone your fork to your machine:
+
+```shell
+git clone https://github.com/your-user-name/OpenROAD.git
+cd OpenROAD
+git remote add upstream https://github.com/The-OpenROAD-Project/OpenROAD.git
+git fetch upstream
+```
+
+This creates the directory `OpenROAD` and connects your repository to
+the upstream (master project) *OpenROAD* repository.
+
+## Creating a branch
+
+You want your master branch to reflect only production-ready code, so create a
+feature branch for making your changes. For example:
+
+```shell
+git checkout master && git branch shiny-new-feature
+git checkout shiny-new-feature
+# Or equivalently, 
+git checkout master && git checkout -b shiny-new-feature
+```
+
+This changes your working directory to the shiny-new-feature branch.  Keep any
+changes in this branch specific to one bug or feature so it is clear
+what the branch brings to OpenROAD. You can have many shiny-new-features
+and switch in between them using the git checkout command.
+
+When creating this branch, make sure your master branch is up to date with
+the latest upstream master version. To update your local master branch, you
+can do:
+
+```shell
+git checkout master
+git pull upstream master
+```
+
+When you want to update the feature branch with changes in master after
+you created the branch, check the section on 
+[updating a PR](#updating-your-pull-request).
+
+## Committing your code
+Keep style fixes to a separate commit to make your pull request more readable. Once you've made changes, you can see them by typing:
+
+```shell
+git status
+```
+
+If you have created a new file, it is not being tracked by git. Add it by typing:
+```shell
+git add path/to/file-to-be-added.py
+```
+
+Doing `git status` again should give something like:
+```shell
+# On branch shiny-new-feature
+#
+#       modified:   /relative/path/to/file-you-added.py
+#
+```
+
+Finally, commit your changes to your local repository with an explanatory commit
+message. Do note the `-s` option is needed for developer signoff. 
+```shell
+git commit -s -m "your commit message goes here"
+```
+
+## Pushing your changes
+
+When you want your changes to appear publicly on your GitHub page, push your
+forked feature branch's commits:
+
+```shell
+git push origin shiny-new-feature
+```
+
+Here `origin` is the default name given to your remote repository on GitHub.
+You can see the remote repositories:
+
+```shell
+git remote -v
+```
+
+If you added the upstream repository as described above you will see something
+like:
+
+```shell
+origin  https://github.com/your-user-name/OpenROAD.git (fetch)
+origin  https://github.com/your-user-name/OpenROAD.git (push)
+upstream        https://github.com/The-OpenROAD-Project/OpenROAD.git (fetch)
+upstream        https://github.com/The-OpenROAD-Project/OpenROAD.git (push)
+```
+
+Now your code is on GitHub, but it is not yet a part of the OpenROAD project. For that to
+happen, a pull request needs to be submitted on GitHub.
+
+## Review your code
+
+When you're ready to ask for a code review, file a pull request. Before you do, once
+again make sure that you have followed all the guidelines outlined in the [Developer's Guide](./DeveloperGuide.md)
+regarding code style, tests, performance tests, and documentation. You should also
+double check your branch changes against the branch it was based on:
+
+1. Navigate to your repository on GitHub -- https://github.com/your-user-name/OpenROAD
+1. Click on `Branches`
+1. Click on the `Compare` button for your feature branch
+1. Select the `base` and `compare` branches, if necessary. This will be `master` and
+   `shiny-new-feature`, respectively.
+
+## Submitting the pull request
+
+If everything looks good, you are ready to make a pull request. A pull request is how
+code from a local repository becomes available to the GitHub community and can be looked
+at and eventually merged into the master version. This pull request and its associated
+changes will eventually be committed to the master branch and available in the next
+release. To submit a pull request:
+
+1. Navigate to your repository on GitHub
+1. Click on the ``Compare & pull request`` button
+1. You can then click on ``Commits`` and ``Files Changed`` to make sure everything looks
+   okay one last time
+1. Write a description of your changes in the ``Preview Discussion`` tab
+1. Click ``Send Pull Request``.
+
+This request then goes to the repository maintainers, and they will review
+the code.
+
+## Updating your pull request
+
+Based on the review you get on your pull request, you will probably need to make
+some changes to the code. In that case, you can make them in your branch,
+add a new commit to that branch, push it to GitHub, and the pull request will be
+automatically updated.  Pushing them to GitHub again is done by:
+
+```shell
+git push origin shiny-new-feature
+```
+
+This will automatically update your pull request with the latest code and restart the
+[Continuous Integration](./CI.md) tests.
+
+Another reason you might need to update your pull request is to solve conflicts
+with changes that have been merged into the master branch since you opened your
+pull request.
+
+To do this, you need to `merge upstream master` in your branch:
+
+```shell
+git checkout shiny-new-feature
+git fetch upstream
+git merge upstream/master
+```
+
+If there are no conflicts (or they could be fixed automatically), a file with a
+default commit message will open, and you can simply save and quit this file.
+
+If there are merge conflicts, you need to solve those conflicts. See 
+this [article](https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/)
+for an explanation on how to do this.
+Once the conflicts are merged and the files where the conflicts were solved are
+added, you can run ``git commit`` to save those fixes.
+
+If you have uncommitted changes at the moment you want to update the branch with
+master, you will need to ``stash`` them prior to updating. 
+
+```{seealso}
+See the stash [docs](https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning).
+```
+This will effectively store your changes and they can be reapplied after updating.
+
+After the feature branch has been updated locally, you can now update your pull
+request by pushing to the branch on GitHub:
+
+```shell
+git push origin shiny-new-feature
+```
+
+## Tips for a successful pull request
+
+If you have made it to the `Review your code` phase, one of the core contributors may
+take a look. Please note however that a handful of people are responsible for reviewing
+all of the contributions, which can often lead to bottlenecks.
+
+To improve the chances of your pull request being reviewed, you should:
+
+- **Reference an open issue** for non-trivial changes to clarify the PR's purpose
+- **Ensure you have appropriate tests**. These should be the first part of any PR
+- **Keep your pull requests as simple as possible**. Larger PRs take longer to review
+- **Ensure that CI is in a green state**. Reviewers may not even look otherwise
+- **Keep updating your pull request**, either by request or every few days
+
+## Acknowledgements
+
+This page has been adapted from [pandas Developer Guide](https://pandas.pydata.org/docs/development/contributing.html). 

docs/_vendor/openroad/README.md

@@ -0,0 +1,57 @@
+# Vendored OpenROAD documentation sources
+
+**Do not edit these files by hand.** They are verbatim copies of files from the
+[OpenROAD](https://github.com/The-OpenROAD-Project/OpenROAD) repository, taken at
+the exact commit that the `tools/OpenROAD` submodule pins. `SOURCE.json` records
+the repository, the commit SHA, and the upstream path of every file here.
+
+| File | Upstream path | Used by `docs/conf.py` to build |
+| --- | --- | --- |
+| `GitGuide.md` | `docs/contrib/GitGuide.md` | `docs/contrib/GitGuide.md` (renamed for ORFS, with `contrib/GitGuideAdapter.md` spliced in) |
+| `index-SupportedOS.md` | `docs/index.md`, `## Supported Operating Systems` section only | that section, demoted to `####`, spliced into `docs/index2.md` under `### Setup` |
+| `utl-README.md` | `src/utl/README.md` | `docs/Manpage.md` |
+
+Only what `docs/conf.py` consumes is stored. OpenROAD's `docs/index.md` is a
+landing page and ORFS renders exactly one section of it, so the refresh script
+extracts that section and vendors it alone — copying the whole page in would
+bring unrelated project prose into this repository to render one table.
+
+The repo-relative links in `utl-README.md` are rewritten to absolute GitHub URLs
+at the vendored SHA, because they would otherwise resolve against this
+repository and 404.
+
+These files are exempt from the whitespace checks in `.gitattributes`: they are
+byte-for-byte upstream copies, and the refresh script is only idempotent if
+nothing rewrites them.
+
+## Why these are vendored
+
+`docs/conf.py` used to `requests.get()` all three files from
+`raw.githubusercontent.com/.../OpenROAD/master/` while Sphinx was running. That
+made the documentation build require network access, produced non-reproducible
+output, tracked OpenROAD `master` rather than the version ORFS actually ships,
+and overwrote files in the working tree on every local `make html`. Vendoring
+gives the documentation the same hash-pinned reproducibility as
+`docs/requirements_lock.txt`.
+
+## Refreshing
+
+```shell
+python3 docs/scripts/refresh_openroad_docs.py
+```
+
+This is the only thing that downloads from GitHub, and it is wired into
+`.github/workflows/github-actions-cron-update-OR.yml` so the nightly
+submodule-bump PR carries the refreshed docs in the same commit. Run it by hand
+whenever you bump `tools/OpenROAD` yourself.
+
+## Checking
+
+```shell
+python3 docs/scripts/check_vendored_docs.py
+```
+
+Asserts, offline, that `SOURCE.json`'s SHA still matches
+`git rev-parse HEAD:tools/OpenROAD`, that every heading `docs/conf.py` splices
+on is still present, and that `index-SupportedOS.md` still holds exactly one
+`##` section. Run it on any pull request that bumps `tools/OpenROAD`.