NatSpec: repository-relative Git Source links via fix-links.py

contracts/README.md

@@ -73,7 +73,6 @@ From `contracts/`:
 forge build
 forge test
 forge fmt
-forge doc --out docs/natspec
 anvil
 ```
 
@@ -82,7 +81,8 @@ Use these when iterating locally:
 - `forge build` builds the contracts.
 - `forge test` runs the Foundry test suite.
 - `forge fmt` formats Solidity sources.
-- `forge doc --out docs/natspec` regenerates the NatSpec reference pages.
+- `python3 docs/natspec/fix-links.py` normalises links in the committed NatSpec
+  reference pages; `docs/natspec/README.md` explains how they are maintained.
 - `anvil` starts a local EVM node outside the sandbox.
 
 Recent coverage additions include:

contracts/docs/natspec/README.md

@@ -6,24 +6,29 @@ This folder contains the generated NatSpec contract reference for
 Start with [`src/README.md`](./src/README.md), which is the generated index for
 the contract tree.
 
-Regenerate the reference from `contracts/` with:
+The committed pages are mdBook Markdown generated by an earlier Foundry release.
+Foundry 1.8.6, the version pinned for Contracts CI, no longer emits that format:
+`forge doc --out docs/natspec` now writes a Vocs site scaffold (`src/pages/*.mdx`,
+`package.json`, `vocs.config.ts`, `vocs.sidebar.ts`) and leaves the mdBook tree
+untouched. The Vocs output is not used here; delete it if `forge doc` creates it.
+
+Keep the reference current by editing the affected pages under `src/src/` when a
+contract's source or NatSpec comments change, then run, from `contracts/`:
 
 ```console
-forge doc --out docs/natspec
 python3 docs/natspec/fix-links.py
 ```
 
 Notes:
 
-- The generated Markdown is intended to be committed alongside the source so it
-  is browsable in the repository.
-- `forge doc` currently emits root-relative links such as `/src/...` that do
-  not browse correctly from the committed `docs/natspec/` tree. Run
-  `python3 docs/natspec/fix-links.py` after regeneration to rewrite those links
-  for repository browsing.
-- The generated `Git Source` links embed the current commit hash at generation
-  time, so rerun `forge doc --out docs/natspec` after source or NatSpec comment
-  changes and before cutting a release or finalising a commit that updates the
-  contracts.
+- The Markdown is committed alongside the source so it is browsable in the
+  repository.
+- `fix-links.py` rewrites root-relative links such as `/src/...` so they browse
+  from the committed tree, turns each `Git Source` link into a repository-relative
+  link to `contracts/src/`, and rewrites the relative links in the homepage
+  (`src/README.md`, a copy of `contracts/README.md`). The script is idempotent:
+  a second run changes nothing.
+- `Git Source` links are relative, so they resolve at whatever commit the page is
+  viewed at, and `check-markdown-links.py` validates them.
 - `book/` output is intentionally ignored; generate it locally only when you
   need a built site.

contracts/docs/natspec/fix-links.py

@@ -9,21 +9,53 @@
 
 DOC_ROOT = Path(__file__).resolve().parent
 GENERATED_ROOT = DOC_ROOT / "src"
+CONTRACTS_ROOT = DOC_ROOT.parent.parent
+HOMEPAGE = GENERATED_ROOT / "README.md"
 LINK_PATTERN = re.compile(r"(!?\[([^\]]+)\]\()([^)]+)(\))")
+# forge doc runs with contracts/ as the project root, so its Git Source links
+# omit the contracts/ prefix and pin the commit the pages were generated at.
+GIT_SOURCE_PATTERN = re.compile(r"^https://github\.com/[^/]+/[^/]+/blob/[^/]+/src/(.+)$")
+
+
+def relative_to(source_file: Path, destination: Path) -> str:
+    return Path(os.path.relpath(destination, source_file.parent)).as_posix()
+
+
+def rewrite_homepage_target(target: str) -> str:
+    # The homepage is a copy of contracts/README.md, whose relative links are
+    # written against contracts/. Rewrite only links that do not resolve from
+    # the homepage but do resolve from contracts/, so a second run is a no-op.
+    if re.match(r"^[a-z][a-z0-9+.-]*:", target) or target.startswith(("#", "/")):
+        return target
+    target_path, _, fragment = target.partition("#")
+    if not target_path or (HOMEPAGE.parent / target_path).exists():
+        return target
+    destination = CONTRACTS_ROOT / target_path
+    if not destination.exists():
+        return target
+    relative = relative_to(HOMEPAGE, destination)
+    return f"{relative}#{fragment}" if fragment else relative
 
 
 def rewrite_target(source_file: Path, target: str, label: str) -> str:
     if target.startswith("/src/"):
         target_path, _, fragment = target.partition("#")
         destination = GENERATED_ROOT / target_path.lstrip("/")
-        relative = Path(os.path.relpath(destination, source_file.parent)).as_posix()
+        relative = relative_to(source_file, destination)
         if fragment:
             relative = f"{relative}#{fragment}"
         return relative
 
     if target.startswith("/dependencies/"):
         return label
 
+    git_source = GIT_SOURCE_PATTERN.match(target)
+    if label == "Git Source" and git_source:
+        return relative_to(source_file, CONTRACTS_ROOT / "src" / git_source.group(1))
+
+    if source_file == HOMEPAGE:
+        return rewrite_homepage_target(target)
+
     return target
 
 

contracts/docs/natspec/src/README.md

@@ -73,7 +73,6 @@ From `contracts/`:
 forge build
 forge test
 forge fmt
-forge doc --out docs/natspec
 anvil
 ```
 
@@ -82,7 +81,8 @@ Use these when iterating locally:
 - `forge build` builds the contracts.
 - `forge test` runs the Foundry test suite.
 - `forge fmt` formats Solidity sources.
-- `forge doc --out docs/natspec` regenerates the NatSpec reference pages.
+- `python3 docs/natspec/fix-links.py` normalises links in the committed NatSpec
+  reference pages; `docs/natspec/README.md` explains how they are maintained.
 - `anvil` starts a local EVM node outside the sandbox.
 
 Recent coverage additions include:

contracts/docs/natspec/src/src/broker/Broker.sol/contract.Broker.md

@@ -1,5 +1,5 @@
 # Broker
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/broker/Broker.sol)
+[Git Source](../../../../../../src/broker/Broker.sol)
 
 **Inherits:**
 [ClientList](../ClientList.sol/contract.ClientList.md)

contracts/docs/natspec/src/src/broker/ClientList.sol/contract.ClientList.md

@@ -1,5 +1,5 @@
 # ClientList
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/broker/ClientList.sol)
+[Git Source](../../../../../../src/broker/ClientList.sol)
 
 **Inherits:**
 AccessControl

contracts/docs/natspec/src/src/broker/ClientList.sol/struct.ClientAddresses.md

@@ -1,5 +1,5 @@
 # ClientAddresses
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/broker/ClientList.sol)
+[Git Source](../../../../../../src/broker/ClientList.sol)
 
 
 ```solidity

contracts/docs/natspec/src/src/common/Allowlist.sol/abstract.Allowlist.md

@@ -1,5 +1,5 @@
 # Allowlist
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/common/Allowlist.sol)
+[Git Source](../../../../../../src/common/Allowlist.sol)
 
 **Inherits:**
 AccessControl

contracts/docs/natspec/src/src/common/AllowlistUpgradeable.sol/abstract.AllowlistUpgradeable.md

@@ -1,5 +1,5 @@
 # AllowlistUpgradeable
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/common/AllowlistUpgradeable.sol)
+[Git Source](../../../../../../src/common/AllowlistUpgradeable.sol)
 
 **Inherits:**
 AccessControlUpgradeable

contracts/docs/natspec/src/src/common/Errors.sol/library.Errors.md

@@ -1,5 +1,5 @@
 # Errors
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/common/Errors.sol)
+[Git Source](../../../../../../src/common/Errors.sol)
 
 
 ## Errors

contracts/docs/natspec/src/src/common/GlobalRegistry.sol/contract.GlobalRegistry.md

@@ -1,5 +1,5 @@
 # GlobalRegistry
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/common/GlobalRegistry.sol)
+[Git Source](../../../../../../src/common/GlobalRegistry.sol)
 
 **Inherits:**
 Ownable

contracts/docs/natspec/src/src/common/QuickVerify.sol/contract.QuickVerify.md

@@ -1,5 +1,5 @@
 # QuickVerify
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/common/QuickVerify.sol)
+[Git Source](../../../../../../src/common/QuickVerify.sol)
 
 **Title:**
 QuickVerify

contracts/docs/natspec/src/src/common/Roles.sol/library.Roles.md

@@ -1,5 +1,5 @@
 # Roles
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/common/Roles.sol)
+[Git Source](../../../../../../src/common/Roles.sol)
 
 
 ## Constants

contracts/docs/natspec/src/src/common/SettlementInfo.sol/struct.SettlementInfo.md

@@ -1,5 +1,5 @@
 # SettlementInfo
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/common/SettlementInfo.sol)
+[Git Source](../../../../../../src/common/SettlementInfo.sol)
 
 
 ```solidity

contracts/docs/natspec/src/src/csd/BaseSecurityToken.sol/abstract.BaseSecurityToken.md

@@ -1,5 +1,5 @@
 # BaseSecurityToken
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/csd/BaseSecurityToken.sol)
+[Git Source](../../../../../../src/csd/BaseSecurityToken.sol)
 
 **Inherits:**
 Initializable, ERC20Upgradeable, AccessControlUpgradeable, [AllowlistUpgradeable](../../common/AllowlistUpgradeable.sol/abstract.AllowlistUpgradeable.md)

contracts/docs/natspec/src/src/csd/DvP.sol/contract.DvP.md

@@ -1,5 +1,5 @@
 # DvP
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/csd/DvP.sol)
+[Git Source](../../../../../../src/csd/DvP.sol)
 
 **Inherits:**
 AccessControl

contracts/docs/natspec/src/src/csd/OrderBook.sol/contract.OrderBook.md

@@ -1,5 +1,5 @@
 # OrderBook
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/csd/OrderBook.sol)
+[Git Source](../../../../../../src/csd/OrderBook.sol)
 
 **Inherits:**
 [IOrderBook](../../interfaces/IOrderBook.sol/interface.IOrderBook.md), AccessControl, ReentrancyGuard

contracts/docs/natspec/src/src/csd/OrderBookFactory.sol/contract.OrderBookFactory.md

@@ -1,5 +1,5 @@
 # OrderBookFactory
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/csd/OrderBookFactory.sol)
+[Git Source](../../../../../../src/csd/OrderBookFactory.sol)
 
 **Inherits:**
 AccessControl

contracts/docs/natspec/src/src/csd/StockToken.sol/contract.StockToken.md

@@ -1,5 +1,5 @@
 # StockToken
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/csd/StockToken.sol)
+[Git Source](../../../../../../src/csd/StockToken.sol)
 
 **Inherits:**
 [BaseSecurityToken](../BaseSecurityToken.sol/abstract.BaseSecurityToken.md)

contracts/docs/natspec/src/src/csd/StockTokenFactory.sol/contract.StockTokenFactory.md

@@ -1,5 +1,5 @@
 # StockTokenFactory
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/csd/StockTokenFactory.sol)
+[Git Source](../../../../../../src/csd/StockTokenFactory.sol)
 
 **Title:**
 StockTokenFactory

contracts/docs/natspec/src/src/interfaces/IOrderBook.sol/interface.IOrderBook.md

@@ -1,5 +1,5 @@
 # IOrderBook
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/interfaces/IOrderBook.sol)
+[Git Source](../../../../../../src/interfaces/IOrderBook.sol)
 
 
 ## Functions

contracts/docs/natspec/src/src/norges-bank/BondAuction.sol/contract.BondAuction.md

@@ -1,5 +1,5 @@
 # BondAuction
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/norges-bank/BondAuction.sol)
+[Git Source](../../../../../../src/norges-bank/BondAuction.sol)
 
 **Inherits:**
 [IBondAuction](../interfaces/IBondAuction.sol/interface.IBondAuction.md), AccessControl, EIP712

contracts/docs/natspec/src/src/norges-bank/BondDvP.sol/contract.BondDvP.md

@@ -1,5 +1,5 @@
 # BondDvP
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/norges-bank/BondDvP.sol)
+[Git Source](../../../../../../src/norges-bank/BondDvP.sol)
 
 **Inherits:**
 AccessControl, [IBondDvP](../interfaces/IBondDvP.sol/interface.IBondDvP.md)

contracts/docs/natspec/src/src/norges-bank/BondManager.sol/contract.BondManager.md

@@ -1,5 +1,5 @@
 # BondManager
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/norges-bank/BondManager.sol)
+[Git Source](../../../../../../src/norges-bank/BondManager.sol)
 
 **Inherits:**
 [IBondManager](../interfaces/IBondManager.sol/interface.IBondManager.md), AccessControl

contracts/docs/natspec/src/src/norges-bank/BondToken.sol/contract.BondToken.md

@@ -1,5 +1,5 @@
 # BondToken
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/norges-bank/BondToken.sol)
+[Git Source](../../../../../../src/norges-bank/BondToken.sol)
 
 **Inherits:**
 [IBondToken](../interfaces/IBondToken.sol/interface.IBondToken.md), ERC1410, AccessControl

contracts/docs/natspec/src/src/norges-bank/ERC1410/ERC1410.sol/contract.ERC1410Minimal.md

@@ -1,5 +1,5 @@
 # ERC1410Minimal
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/norges-bank/ERC1410/ERC1410.sol)
+[Git Source](../../../../../../../src/norges-bank/ERC1410/ERC1410.sol)
 
 **Inherits:**
 [IERC1410](../IERC1410.sol/interface.IERC1410.md), ERC165

contracts/docs/natspec/src/src/norges-bank/ERC1410/IERC1410.sol/interface.IERC1410.md

@@ -1,5 +1,5 @@
 # IERC1410
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/norges-bank/ERC1410/IERC1410.sol)
+[Git Source](../../../../../../../src/norges-bank/ERC1410/IERC1410.sol)
 
 **Inherits:**
 IERC165

contracts/docs/natspec/src/src/norges-bank/Wnok.sol/contract.Wnok.md

@@ -1,5 +1,5 @@
 # Wnok
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/norges-bank/Wnok.sol)
+[Git Source](../../../../../../src/norges-bank/Wnok.sol)
 
 **Inherits:**
 ERC20, AccessControl, [Allowlist](../../common/Allowlist.sol/abstract.Allowlist.md)

contracts/docs/natspec/src/src/norges-bank/interfaces/IBondAuction.sol/interface.IBondAuction.md

@@ -1,5 +1,5 @@
 # IBondAuction
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/norges-bank/interfaces/IBondAuction.sol)
+[Git Source](../../../../../../../src/norges-bank/interfaces/IBondAuction.sol)
 
 Interface for the Bond Auction contract.
 

contracts/docs/natspec/src/src/norges-bank/interfaces/IBondDvP.sol/interface.IBondDvP.md

@@ -1,5 +1,5 @@
 # IBondDvP
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/norges-bank/interfaces/IBondDvP.sol)
+[Git Source](../../../../../../../src/norges-bank/interfaces/IBondDvP.sol)
 
 Interface for the Bond delivery-versus-payment contract.
 

contracts/docs/natspec/src/src/norges-bank/interfaces/IBondManager.sol/interface.IBondManager.md

@@ -1,5 +1,5 @@
 # IBondManager
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/norges-bank/interfaces/IBondManager.sol)
+[Git Source](../../../../../../../src/norges-bank/interfaces/IBondManager.sol)
 
 Interface for the Bond Manager contract.
 

contracts/docs/natspec/src/src/norges-bank/interfaces/IBondToken.sol/interface.IBondToken.md

@@ -1,5 +1,5 @@
 # IBondToken
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/norges-bank/interfaces/IBondToken.sol)
+[Git Source](../../../../../../../src/norges-bank/interfaces/IBondToken.sol)
 
 **Inherits:**
 [IERC1410](../../ERC1410/IERC1410.sol/interface.IERC1410.md)

contracts/docs/natspec/src/src/private-bank/ITbd.sol/interface.ITbd.md

@@ -1,5 +1,5 @@
 # ITbd
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/private-bank/ITbd.sol)
+[Git Source](../../../../../../src/private-bank/ITbd.sol)
 
 
 ## Functions

contracts/docs/natspec/src/src/private-bank/Tbd.sol/contract.Tbd.md

@@ -1,5 +1,5 @@
 # Tbd
-[Git Source](https://github.com/Norges-Bank-CBDC-Lab/cbdc-tokenization-sandbox/blob/e1ad13913c0726f3f8165cafaa1413435020decc/src/private-bank/Tbd.sol)
+[Git Source](../../../../../../src/private-bank/Tbd.sol)
 
 **Inherits:**
 [ITbd](../ITbd.sol/interface.ITbd.md), IERC1363Receiver, ERC20, AccessControl, [Allowlist](../../common/Allowlist.sol/abstract.Allowlist.md)