lowRISC / lowRISC/opentitan

[docs] Documentation rendering fails on `earlgrey_es_sival`

Open
#24,772 1 comment 0 reactions 3 assignees View on GitHub

@jwnrt is already working on this.

Since Oct 11, 2024.

Component:Doc Component:Tooling
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.