Readthedocs render

[liamhuber]

The build doesn't crash, but it's not showing the content either. For starters, let's add the myst dependency, which should be needed for rendering the markdown file.

[github-actions]

👈 Launch a binder notebook on branch pyiron/pyiron_ontology/myst_docs

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
✅ +0.00% (target: -1.00%)	✅ ∅

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (64d7422)	459	418	91.07%
Head commit (7f400b6)	459 (+0)	418 (+0)	91.07% (+0.00%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#36)	0	0	∅ (not applicable)

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

_{You may notice some variations in coverage metrics with the latest Coverage engine update. For more details, visit the documentation}

[liamhuber]

The class diagrams don't render, and the API documentation is not triggering

[liamhuber]

API docs are working, but the mermaid diagrams are still not rendering

[liamhuber]

Ugh, it looks even worse now

[liamhuber]

Ok, the readthedocs logs have the following line: WARNING: command 'mmdc' cannot be run (needed for mermaid output), check the mermaid_cmd setting which is probably the source of the trouble

[liamhuber]

I found some random github issue suggesting that the mermaid cli needs to be involved, and then had the pragmatic idea to just go do whatever the sphinxcontrib-mermaid folks are doing for their readthedocs because it's obviously working for them! Sure enough, they install the mermaid cli on readthedocs. Let's try it.

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
✅ +0.00% (target: -1.00%)	∅

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (64d7422)	459	418	91.07%
Head commit (9f51a6f)	459 (+0)	418 (+0)	91.07% (+0.00%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#36)	0	0	∅ (not applicable)

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

_{You may notice some variations in coverage metrics with the latest Coverage engine update. For more details, visit the documentation}

[liamhuber]

The readthedocs log has the following error:

writing... WARNING: mm code 'classDiagram\n    class PyironOntoThing\n    PyironOntoThing: get_sources()\n    <<Abstract>> PyironOntoThing\n    WorkflowThing <|--PyironOntoThing\n    <<Abstract>> WorkflowThing\n    Parameter <|--PyironOntoThing\n    <<Abstract>> Parameter\n    Function <|--WorkflowThing\n    IO <|--Parameter\n    IO <|--WorkflowThing\n    <<Abstract>> IO\n    Input <|--IO\n    Output <|--IO\n    Generic <|--Parameter\n    Generic: is_representable_by()\n    Generic: is_more_specific_than()': Mermaid exited with error:
[stderr]
b'\nTimeoutError: Timed out after 30000 ms while waiting for the WS endpoint URL to appear in stdout!\n    at ChromeLauncher.launch (file:///home/docs/.asdf/installs/nodejs/16.18.1/.npm/lib/node_modules/@mermaid-js/mermaid-cli/node_modules/puppeteer-core/lib/esm/puppeteer/node/ProductLauncher.js:119:23)\n    at async run (file:///home/docs/.asdf/installs/nodejs/16.18.1/.npm/lib/node_modules/@mermaid-js/mermaid-cli/src/index.js:404:19)\n    at async cli (file:///home/docs/.asdf/installs/nodejs/16.18.1/.npm/lib/node_modules/@mermaid-js/mermaid-cli/src/index.js:184:3)\n\n'
[stdout]
b''
done

[liamhuber]

Forcing the output type to PNG worked...or I just needed to re-run; either way the build is correctly showing the diagrams.

Be careful as the failure may re-occur: there are reports of the upstream puppeteer as the root of the timeout error:

[liamhuber]

Actually, the error is still showing up in the raw readthedocs log, but the image is showing in the final rendered docs nonetheless...