[docs] Documentation rendering fails on `earlgrey_es_sival`
@jwnrt is already working on this.
Since Oct 11, 2024.
- Dominant language
- SystemVerilog
- Stars
- 3.6k
- Forks
- 1.1k
- Avg merge
- 2d 22h
- Merged PRs (30d)
- 141
Description
### 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
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.
```
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.