Mermaid diagrams in docs

[stephengreen]

I am unable to compile properly the flow charts in the documentation. This has worked in the past, so I am not sure what the issue is, and I do not see any error message.

Could somebody try compiling the docs to see if it works? You probably need to install the packages

sphinx
sphinx-rtd-theme
myst-nb
sphinxcontrib-mermaid
sphinxcontrib-bibtex
myst-parser
linkify-it-py

[stephengreen]

There are also many warnings when compiling docs, so if somebody would like to figure these out, that would be great.

[mpuerrer]

After installing these packages, what are the commands to build the docs?

[mpuerrer]

I got it to build using sphinx-build -b html docs/source/ docs/build/ after adding the above set of packages to the dependencies in pyproject.toml.

Output is in https://ldas-jobs.ligo.caltech.edu/~michael.puerrer/dingo_docs/, but the flowchart is still broken: https://ldas-jobs.ligo.caltech.edu/~michael.puerrer/dingo_docs/quickstart.html (I've not touched this yet).

There were many warnings and a bunch of errors ERROR: Unexpected indentation. in:

• dingo.gw.waveform_generator.waveform_generator.WaveformGenerator.generate_hplus_hcross
• dingo.gw.transforms.noise_transforms.WhitenAndScaleStrain
• dingo.gw.transforms.noise_transforms.RepackageStrainsAndASDS

In quickstart.md I only see WARNING: Duplicate reference definition: // [myst.ref] but these are towards the end of the file [//]: # () etc, nothing about mermaid.

[mpuerrer]

I tried a few things with mermaid, but nothing worked. Then I noticed that the diagram at the bottom of https://myst-parser.readthedocs.io/en/latest/intro.html appears to be broken and not rendering for me (Safari or Chrome). So, perhaps this is a more general issue.

[nihargupte-ph]

Is this the mermaid diagram?

I was able to get it to render, I think there is some version discrepancy, which is causing it not to render before

[stephengreen]

Yes, how did you compile it?On Feb 26, 2023 11:38, Nihar Gupte @.***> wrote: Is this the mermaid diagram?

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you authored the thread.Message ID: @.***>

[nihargupte-ph]

I installed the packages locally, but didn't install the rest of Dingo, ie I only installed documentation packages. Likely there is some dependency/version issue. Haven't quite figured out what, but now that we have a working version can just check against a broken venv.

If it's not fixed by Tuesday can always just save the image and comment the flowchart code in the .md files temporarily.

[stephengreen]

I upgraded some of my packages (including sphinxcontrib-mermaid) and that seems to have fixed it. It is likely related to this discussion.

However, I noticed another problem: On the main page, the bottom section "Indices and tables" is completely missing...

[stephengreen]

This seems to be a bug with docutils. To fix it requires docutils<0.17, as described here. IGWN uses 0.19, so we can't require the lower version. Probably we should just remember this and be careful when compiling the docs.