search

lowRISC / opentitan

OpenTitan: Open source silicon root of trust
https://www.opentitan.org
Apache License 2.0
2.56k stars 762 forks source link

[docs] Documentation rendering fails on `earlgrey_es_sival` #24772

Open cfrantz opened 1 week ago

cfrantz commented 1 week ago

Description

Documentation rendering fails in CI on the earlgrey_es_sival branch.

Although we may not care about generating documentation for the ES branch, we should understand the source of the doc-build failures so that we can ensure that we can always build documentation for the earlgrey-1.0.0 branch.

Failure in CI:

fetching data for high-speed-crossbar
Traceback (most recent call last):
  File "/home/vsts/work/1/s/util/site/fetch_block_stats.py", line 133, in <module>
    main()
  File "/home/vsts/work/1/s/util/site/fetch_block_stats.py", line 124, in main
    ) = parse_report(block_level_urls[name]) if block['report'] else (None, None)
  File "/home/vsts/work/1/s/util/site/fetch_block_stats.py", line 60, in parse_report
    with urlopen(f'[https://reports.opentitan.org/{path}/report.json'](https://reports.opentitan.org/{path}/report.json')) as response:
  File "/usr/lib/python3.8/urllib/request.py", line 222, in urlopen
    return opener.open(url, data, timeout)
  File "/usr/lib/python3.8/urllib/request.py", line 531, in open
    response = meth(req, response)
  File "/usr/lib/python3.8/urllib/request.py", line 640, in http_response
    response = self.parent.error(
  File "/usr/lib/python3.8/urllib/request.py", line 569, in error
    return self._call_chain(*args)
  File "/usr/lib/python3.8/urllib/request.py", line 502, in _call_chain
    result = func(*args)
  File "/usr/lib/python3.8/urllib/request.py", line 649, in http_error_default
    raise HTTPError(req.full_url, code, msg, hdrs, fp)
urllib.error.HTTPError: HTTP Error 404: Not Found

The apparent cause is that the job is trying to download a DV report which has been deleted from the bucket.

Failure in my local clone of the repo:

Rendering also fails locally when I run the ci/scripts/build-docs.sh script:

$ ./ci/scripts/build-docs.sh 
Build Directory : /home/cfrantz/opentitan/docs/build-site
Building doxygen...
warning: Tag 'HTML_TIMESTAMP' at line 111 of file '/home/cfrantz/opentitan/docs/util/doxygen/Doxyfile' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
Doxygen build complete.
INFO: Invocation ID: 9716987b-5705-4aa5-84fe-a4c31d815b6d
INFO: Analyzed target @crate_index//:mdbook__mdbook (2 packages loaded, 93 targets configured).
INFO: Found 1 target...
INFO: Elapsed time: 0.715s, Critical Path: 0.09s
INFO: 24 processes: 24 internal.
INFO: Build completed successfully, 24 total actions
INFO: Running command line: bazel-bin/external/crate_index__mdbook-0.4.34/mdbook__bin build --dest-dir /home/cfrantz/opentitan/docs/build-site/book/ /home/cfrantz/opentitan/docs
2024-10-11 08:31:21 [INFO] (mdbook::book): Book building has started
2024-10-11 08:31:42 [INFO] (mdbook::book): Running the html backend
2024-10-11 08:32:12 [WARN] (mdbook::renderer::html_handlebars::search): searchindex.json is very large (27179641 bytes)
WARN  DEPRECATED: Kind "taxonomyterm" used in disableKinds is deprecated, use "taxonomy" instead.
WARN  Unknown kind "categories" in disableKinds configuration.
Start building sites … 
hugo v0.124.1+extended linux/amd64 BuildDate=2024-05-30T16:28:11Z VendorInfo=debian:0.124.1-1+build1

Total in 18 ms
Error: error building site: process: readAndProcessContent: "/home/cfrantz/opentitan/docs/site/landing/content/documentation.md:11:1": failed to extract shortcode: template for shortcode "earlgrey-block-diagram" not found
##vso[task.logissue type=error]Documentation build failed.
matutem commented 3 hours ago

This may be related to the very confusing dates in https://github.com/lowRISC/opentitan/blob/master/util/site/fetch_block_stats.py. I would imagine the urls should always be from latest, and "real" branches, like tapeouts, will have separate storage buckets for their results, and there should always be something at their "latest".

But as a safety measure if there are no results the script should handle an error in https://github.com/lowRISC/opentitan/blob/master/util/site/fetch_block_stats.py#L60.