22# Build the PineForge API documentation site.
33#
44# Outputs: docs/site/html/ (static HTML, ready to deploy)
5- # Requires: doxygen, dot (graphviz), curl, awk
5+ # Requires: doxygen, dot (graphviz), curl, awk, python3
66#
77# CI usage: bash docs/build.sh
88# Local: bash docs/build.sh # docs/site/html/index.html
@@ -89,12 +89,198 @@ self_test_doxygen_retry() {
8989 return " $result "
9090}
9191
92+ docs_version_label () {
93+ local exact_tag=" $1 " worktree_status=" $2 "
94+ if [[ -n " $exact_tag " && -z " $worktree_status " ]]; then
95+ printf ' %s\n' " $exact_tag "
96+ else
97+ printf ' %s\n' unreleased
98+ fi
99+ }
100+
101+ self_test_seo () {
102+ if [[ " $( docs_version_label " v1.5.0" " " ) " != " v1.5.0" \
103+ || " $( docs_version_label " " " " ) " != " unreleased" \
104+ || " $( docs_version_label " v1.5.0" " M docs/build.sh" ) " != " unreleased" \
105+ || " $( docs_version_label " v1.5.0" " ?? new-page.md" ) " != " unreleased" ]]; then
106+ echo " ==> FAIL: docs version must be an exact clean tag or unreleased" >&2
107+ return 1
108+ fi
109+ local fixture script result
110+ fixture=" $( mktemp -d " ${TMPDIR:-/ tmp} /pineforge-seo.XXXXXX" ) "
111+ script=" $( cd " $( dirname " $0 " ) " && pwd) /seo_postprocess.py"
112+ cat > " $fixture /check_seo.py" << 'PY '
113+ from html.parser import HTMLParser
114+ from pathlib import Path
115+ import subprocess
116+ import sys
117+ import xml.etree.ElementTree as ET
118+
119+ script = Path(sys.argv[1])
120+ fixture = Path(sys.argv[2])
121+ site = fixture / "html"
122+ site.mkdir()
123+ old_meta = '<meta name="description" content="Old shared description"/>\n'
124+ old_canonical = '<link href="https://example.com/old.html" rel="canonical"/>\n'
125+ duplicate_canonical = '<link rel="canonical" href="https://cdocs.pineforge.dev/other"/>\n'
126+ titles = {
127+ "index.html": "PineForge: Landing",
128+ "x.html": "PineForge: Orders & "fills" <T>",
129+ "other.html": "PineForge: Other reference",
130+ "404.html": "Page not found",
131+ }
132+ bodies = {
133+ "index.html": '''<a href="x.html">X</a>
134+ <a href="index.html">Home</a>
135+ <a href="index.html#start">Start</a>''',
136+ "x.html": '''<a href="other.html#a">Other</a>
137+ <a href="./other.html">Relative</a>
138+ <a title='href="other.html"' data-href="x.html" href="other.html">Tooltip</a>
139+ <a href="https://example.com/x.html">External</a>
140+ <a href="mailto:[email protected] ">Mail</a> 141+ <a href="#frag">Fragment</a>
142+ <a href="other.html#https://example.com">Embedded URL</a>
143+ <a href="//example.com/x.html">Protocol relative</a>
144+ <a href="/other.html">Root path</a>
145+ <a href="../other.html">Parent path</a>
146+ <a href="search/help.html">Search path</a>
147+ <a href="icon.png">Image</a>
148+ <link href="style.css" rel="stylesheet"/>
149+ <script src="links.js"></script>
150+ <script>const text = 'href="other.html"';</script>
151+ <!-- href="other.html" -->''',
152+ "other.html": '<a href="x.html">X</a>',
153+ "404.html": '<p>Page missing.</p><a href="/">Home</a><a href="https://pineforge.dev">pineforge.dev</a>',
154+ }
155+ descriptions = {
156+ "index.html": (
157+ "PineForge's C++17 engine has two layers documented in this API reference: "
158+ "a kernel that knows nothing about PineScript or TradingView and a Pine "
159+ "adapter that reproduces TradingView's execution semantics."
160+ ),
161+ "x.html": "Orders & "fills" <T> — PineForge C++17 engine API documentation.",
162+ "other.html": "Other reference — PineForge C++17 engine API documentation.",
163+ }
164+
165+ def page(title, body, metadata):
166+ return (f"<!doctype html>\n<html><head>\n<title>{title}</title>\n"
167+ f"{metadata}</head>\n<body>\n{body}\n</body></html>\n")
168+
169+ for name, title in titles.items():
170+ metadata = "" if name == "404.html" else old_meta
171+ if name == "other.html":
172+ metadata += old_canonical + duplicate_canonical
173+ (site / name).write_bytes(page(title, bodies[name], metadata).encode("utf-8"))
174+
175+ untouched = {
176+ "links.js": b'const page = "foo.html"; const link = \'href="x.html"\';\r\n',
177+ "style.css": b'/* foo.html */\n',
178+ "search/searchdata.js": b'const page = "foo.html";\n',
179+ "search/help.html": b'<a href="x.html">Nested input stays untouched</a>\n',
180+ }
181+ for name, contents in untouched.items():
182+ (site / name).parent.mkdir(parents=True, exist_ok=True)
183+ (site / name).write_bytes(contents)
184+
185+ expected_bodies = dict(bodies)
186+ expected_bodies["index.html"] = (bodies["index.html"]
187+ .replace('href="x.html"', 'href="x"')
188+ .replace('href="index.html"', 'href="./"')
189+ .replace('href="index.html#start"', 'href="./#start"'))
190+ expected_bodies["x.html"] = (bodies["x.html"]
191+ .replace('<a href="other.html#a">', '<a href="other#a">')
192+ .replace('<a href="./other.html">', '<a href="./other">')
193+ .replace('data-href="x.html" href="other.html">', 'data-href="x.html" href="other">'))
194+ expected_bodies["other.html"] = '<a href="x">X</a>'
195+
196+ class Metadata(HTMLParser):
197+ def __init__(self):
198+ super().__init__(convert_charrefs=True)
199+ self.canonicals = []
200+ self.descriptions = []
201+
202+ def handle_starttag(self, tag, attrs):
203+ attrs = dict(attrs)
204+ if tag == "link" and "canonical" in attrs.get("rel", "").split():
205+ self.canonicals.append(attrs.get("href"))
206+ if tag == "meta" and attrs.get("name") == "description":
207+ self.descriptions.append(attrs.get("content"))
208+
209+ command = [sys.executable, "-I", "-B", str(script), str(site)]
210+ subprocess.run(command, check=True)
211+ parsed_descriptions = []
212+ canonical_urls = {}
213+ for name, title in titles.items():
214+ url = "https://cdocs.pineforge.dev/" + ("" if name == "index.html" else name[:-5])
215+ canonical_urls[name] = url
216+ canonical = f'<link rel="canonical" href="{url}"/>\n'
217+ actual = (site / name).read_bytes().decode("utf-8")
218+ if name == "404.html":
219+ # The error page is left exactly as written: no canonical, no description, no link rewrite.
220+ assert actual == page(title, bodies[name], ""), "404.html must be left untouched"
221+ continue
222+ meta = f'<meta name="description" content="{descriptions[name]}"/>\n'
223+ assert canonical + "</head>" in actual, f"{name}: missing canonical before </head>"
224+ assert actual == page(title, expected_bodies[name], meta + canonical), f"{name}: wrong HTML output"
225+ parsed = Metadata()
226+ parsed.feed(actual)
227+ assert parsed.canonicals == [url], f"{name}: canonical must occur exactly once"
228+ assert len(parsed.descriptions) == 1, f"{name}: description must occur exactly once"
229+ parsed_descriptions.extend(parsed.descriptions)
230+ assert len(set(parsed_descriptions)) == len(titles) - 1, "page descriptions must differ (404 has none)"
231+ assert '<a href="x">X</a>' in (site / "index.html").read_text(), "x.html was not rewritten"
232+ for name, contents in untouched.items():
233+ assert (site / name).read_bytes() == contents, f"{name}: asset or nested page changed"
234+
235+ namespace = "{http://www.sitemaps.org/schemas/sitemap/0.9}"
236+ root = ET.parse(site / "sitemap.xml").getroot()
237+ assert root.tag == namespace + "urlset" and root.attrib == {}, "invalid sitemap urlset"
238+ urls = []
239+ for entry in root:
240+ assert entry.tag == namespace + "url" and entry.attrib == {}, "invalid sitemap entry"
241+ assert len(entry) == 1 and entry[0].tag == namespace + "loc", "sitemap must contain only locations"
242+ assert entry[0].attrib == {}, "sitemap location has unexpected attributes"
243+ urls.append(entry[0].text)
244+ expected_urls = sorted(canonical_urls[path.name] for path in site.glob("*.html") if path.name != "404.html")
245+ assert urls == expected_urls, "sitemap differs from the sorted top-level page set minus 404"
246+
247+ first_pass = {path.relative_to(site): path.read_bytes() for path in site.rglob("*") if path.is_file()}
248+ subprocess.run(command, check=True)
249+ second_pass = {path.relative_to(site): path.read_bytes() for path in site.rglob("*") if path.is_file()}
250+ assert second_pass == first_pass, "a second pass must be byte-identical, including canonical and sitemap"
251+
252+ empty = fixture / "empty"
253+ empty.mkdir()
254+ only_404 = fixture / "only-404"
255+ only_404.mkdir()
256+ (only_404 / "404.html").write_bytes((site / "404.html").read_bytes())
257+ for invalid_site in (empty, only_404, fixture / "missing"):
258+ result = subprocess.run(command[:-1] + [str(invalid_site)], capture_output=True)
259+ assert result.returncode != 0, "missing or empty documentation must fail"
260+ assert not (invalid_site / "sitemap.xml").exists(), "invalid input produced a sitemap"
261+ PY
262+ if python3 -I -B " $fixture /check_seo.py" " $script " " $fixture " ; then
263+ result=0
264+ else
265+ result=$?
266+ fi
267+ rm -rf " $fixture "
268+ if (( result == 0 )) ; then
269+ echo " ==> Docs SEO self-test: canonical, links, descriptions, sitemap, assets, version ... OK"
270+ fi
271+ return " $result "
272+ }
273+
92274if [[ " ${1:- } " == " --self-test-retry" && " $# " == 1 ]]; then
93275 self_test_doxygen_retry
94276 exit $?
95277fi
278+ if [[ " ${1:- } " == " --self-test-seo" && " $# " == 1 ]]; then
279+ self_test_seo
280+ exit $?
281+ fi
96282if (( $# != 0 )) ; then
97- echo " usage: docs/build.sh [--self-test-retry]" >&2
283+ echo " usage: docs/build.sh [--self-test-retry|--self-test-seo ]" >&2
98284 exit 2
99285fi
100286
@@ -120,11 +306,12 @@ if [[ ! -f "$THEME_DIR/.version" ]] \
120306 echo " $DOXYGEN_AWESOME_VERSION " > " $THEME_DIR /.version"
121307fi
122308
123- # 2. Resolve project version from VERSION file (or git tag if available).
124- VERSION=" $( cat ../VERSION 2> /dev/null || echo unknown) "
125- if command -v git > /dev/null 2>&1 && git -C .. rev-parse --git-dir > /dev/null 2>&1 ; then
126- GIT_VERSION=" $( git -C .. describe --tags --dirty --always 2> /dev/null || true) "
127- [[ -n " $GIT_VERSION " ]] && VERSION=" $GIT_VERSION "
309+ # 2. Label only a clean, exactly tagged checkout as a release.
310+ VERSION=" unreleased"
311+ if command -v git > /dev/null 2>&1 \
312+ && GIT_VERSION=" $( git -C .. describe --tags --exact-match 2> /dev/null) " \
313+ && GIT_STATUS=" $( git -C .. status --porcelain 2> /dev/null) " ; then
314+ VERSION=" $( docs_version_label " $GIT_VERSION " " $GIT_STATUS " ) "
128315fi
129316echo " ==> Building docs for PineForge $VERSION "
130317
@@ -136,6 +323,7 @@ CONFIG="$(mktemp "${TMPDIR:-/tmp}/pineforge-doxyfile.XXXXXX")"
136323trap ' rm -f "$CONFIG"' EXIT
137324{ cat Doxyfile; echo " PROJECT_NUMBER = $VERSION " ; } > " $CONFIG "
138325run_doxygen_with_retry
326+ python3 -I -B seo_postprocess.py site/html
139327
140328# 3b. The scoped warning gate (R5 lane L14-A).
141329#
0 commit comments