This project is aiming to create a more modern and integrated view on the IVOA standard documents, that can comfortably be viewed on many different device sizes. It aims to do this by transforming the source of the documents using pandoc and then putting them into a structure delivered using sphinx. Once complete, it is hoped that this is a more accessible resource for developers to use to understand how to write code compliant with IVOA standards.
It is specifically not intended to change or replace the standard IVOA document publishing system. Although perhaps a long term aim, if successful, might be to influence style of the content of the standards documents - however, there will always be a conflict between the designed for academic paper delivery style and a more on-line documentation approach.
This is still in the proof of concept stage, so there are many faults. Mostly because not all the transformations below have been implemented yet.
The result of running the process is available in GitHub Pages
The desired transformations to make the documents more "readable" online are
- remove some of the front matter from each document
- have a single bibliography
- transform citation links to other standards as internal URLs - it can take 4 clicks to navigate from a citation one document to the content of another in the standard publishing
The original source documents are in src as git submodule references to the original GitHub projects in the ivoa-std organisation. These documents are transformed into the sphinxSource/idoc directory tree. The other content under sphinxSource forms the "framework" site in which the autogenerated documentation sits.
make
Should build the site which is then viewable at ./build/html/index.html.
To ensure that you are building from a clean initial state
make clean doSphinx
Note
If developing this site on MacOS you should note that the "standard" make is still v3.x - the makefiles here require v4.x (they will silently just not do things) and so it is necessary to install a newer version via for instance homebrew (and note it is still not put on the default PATH)
During the build the ivoadoc submodules are manipulated in a way that means that git commit will not work - to restore the ivoadoc submodules run
make restore_ivoatex
Should allow git commands to work normally.
Git submodules that exist in src can be difficult to manage - especially when trying to make sure that they point to the latest git commit hash for the module - this should do that.
git submodule update --recursive --remote
GitHub actions are set up to build and publish the site automatically. The build will happen on PRs and pushes to the main branch - it creates an artifact containing the site for each action invocation. The publishing to github pages will automatically occur on a successful build on the main branch.
In general there is customization required for two reasons
- pandoc's default translation from latex to restructured text does not quite work as required
- to perform one of the desired transformations
Customisation is done via https://pandoc.org/lua-filters.html, in the pandocCustomization directory with some examples in https://github.com/pandoc-ext and lua language guide https://www.lua.org/pil/contents.html