[PROJECT IDEA] Fork the schema reference site

[andylolz]

Rationale

There are a few issues with the existing reference site that it would be useful to address:

• Sidebar navigation is a bit confusing, because the submenu below the active page isn’t default expanded
• Rules are expressed in a confusing way
• It is very slow
• It is only available in English
• Switching versions is a bit clunky
• There’s no way to do in-page links
• […]

Proposal

• We can use Ben’s Schema2Doc code, and then use sphinx to generate HTML from RST
• We can start from the theme on https://github.com/IATI/IATI-Websites and then iterate from there
• It can be hosted on github pages (v fast) and built by a github action (good to do CI)

[andylolz]

I’ve made a start on this here:
https://reference.codeforiati.org

[matmaxgeds]

Loathe to say this as it means more work that I am not qualified to do, but is there an option to pipe it into readthedocs or similar? Whatever the outcome is, I guess we should be prepared to constantly backport new updates done to the official site - if this couldn't be automatic, this might be more work than we can handle?

[andylolz]

is there an option to pipe it into readthedocs or similar?

Yes, that’s exactly what I’d like to do! We should be able to put a readthedocs-style template onto sphinx, which gets us a few of the things in the list above.

I guess we should be prepared to constantly backport new updates done to the official site - if this couldn't be automatic, this might be more work than we can handle?

So, my hope on this is that we can do it automatically. However… Significant changes have been made to IATI-Extra-Documentation to make it compatible with wagtail, so it’s not totally clear yet how easy it will be. (I’ve had to use a very old version of that repo in order to get it working on https://reference.codeforiati.org).

I’m still hopeful at the moment that we can mirror IATI’s source code, and automatically pull in changes as they occur. That’s what we do currently with IATI-Codelists-NonEmbedded, see for example here: codeforIATI/IATI-Codelists-NonEmbedded#61

[andylolz]

I’ve started a new ticket about this here: codeforIATI/reference#3.