Test RST rendering on GitHub

[ml-evs]

See #492

[vaitkus]

This one does render properly. So do some more complex rst files on other repos, e.g. https://github.com/rstcheck/rstcheck/blob/main/README.rst.

[ml-evs]

Hmmm yeah, trying to pin down which version stops rendering for us (it still seems like a recent change). If this is a rendering timeout issue, maybe this is a good excuse to cut down the complexity of the specification with @rartino's properties...

[rartino]

Probably the same thing; rich diffs for PRs against optimade.rst now gives the error:

Oh My

Sorry... we’re unable to render the document prior to diffing.

[ml-evs]

Old versions like https://github.com/Materials-Consortia/OPTIMADE/blob/6f1e115094ec256c262df712a35c86f4d3e6d1c7/optimade.rst fail to render when they definitely used to (Firefox Developer Edition, no extensions)

[ml-evs]

Will close this to not pollute PRs, we can continue discussing at #492

[ml-evs]

Okay, the first 312 lines of the spec render... https://github.com/Materials-Consortia/OPTIMADE/blob/3ba8299979001f0cfdd02bde55d241a9b2a3d9d3/optimade.rst

[rartino]

Okay, the first 312 lines of the spec render... https://github.com/Materials-Consortia/OPTIMADE/blob/3ba8299979001f0cfdd02bde55d241a9b2a3d9d3/optimade.rst

Maybe a sign that it is time to split it into separate files?...

[ml-evs]

And there's no issue using custom roles/toc (in isolation, at least, could still be added complexity once the file is too large)

[ml-evs]

Okay, the first 312 lines of the spec render... https://github.com/Materials-Consortia/OPTIMADE/blob/3ba8299979001f0cfdd02bde55d241a9b2a3d9d3/optimade.rst

Maybe a sign that it is time to split it into separate files?...

Sure, but for now we still won't have enough space to describe what's in those files (assuming you mean properties at least!)

[rartino]

Sure, but for now we still won't have enough space to describe what's in those files (assuming you mean properties at least!)

I mean chopping it up into chapters (and re-merge when rendering). It is a bit finky with the TOC, will require some non-trivial infrastructure work.

[ml-evs]

Sure, but for now we still won't have enough space to describe what's in those files (assuming you mean properties at least!)

I mean chopping it up into chapters (and re-merge when rendering). It is a bit finky with the TOC, will require some non-trivial infrastructure work.

Sure, if each individual .rst can still be previewed fine. I still have https://ml-evs.science/OPTIMADE/optimade.html going, could also put some work into making this multi-versioned and deployed sensibly, as the "real" specification for users to view.

[ml-evs]

As a yardstick, addition of this patch (b177978) is what breaks rendering (as of today). I'll try to see if there's any weird feature we're using here that is causing it to lag

[blokhin]

Since the spec becomes a standalone HTML document, not necessary connected to a GitHub-org, let's later add the "Community" section to the Appendix, so that the reader might get some idea about the Optimade people without googling.