Open CasperWA opened 3 years ago
Decoupling OPTIMADE's permanent URLs from GitHub is good indeed!
My immediate thought is under the 'schema' repository I just created. But maybe it would be confusing with:
https://schemas.optimade.org/specification/v1.0/optimade.html
although, in a very generalized sense, the specification is a schema (for humans) :-)
Seeing 'schemas', I myself tend to think about OpenAPI/JSON schemas, but maybe that's just me :smile:. As a project OPTIMADE needs to establish common terms for things. I would prefer calling human-readable specification a "specification", and computer-readable specification a "schema". To me it seems that we have done so up to now, but I may be wrong.
Did I do a mistake naming that domain 'schemas'? Should it has been something like 'permanent.optimade.org'?...
I don't think we need a specific domain for permanent URLs. I think that everything that falls under versioned URLs must be permanent.
I don't think we need a specific domain for permanent URLs. I think that everything that falls under versioned URLs must be permanent.
Well, I have seen websites be restructured to a point where I think it is a good idea to generally isolate things that absolutely needs permanent URLs far away from the "end-user facing" URL structure. That was why I directly pushed for a separate https://schemas.optimade.org/
so that many years from now, my saved OPTIMADE output results can still be validated with the embedded schema URLs.
But, I suppose the permalinks to the specification texts are a bit less sensitive then the machine-readable schemas.
So, what URL do we place them under then? https://www.optimade.org/s/specification/v1.0/optimade.html
(Where the extra '/s/' for "static" is a somewhat common trick to avoid issues that could show up if we at a future website restructuring change our minds and think that the website really needs to start use the "/specification" URL tree.)
I would like a readable version of the specification hosted at the suggested URL above. Currently we run GitHub pages from the master branch of this repo, which provides us with http://www.optimade.org/OPTIMADE/.
I guess we want a GitHub action that runs for GitHub releases and renders the HTML to a new branch (canonically gh_pages
) that we can then use to host e.g. https://optimade.org/s/specification/v1.0/optimade.html etc for each released specification version. I found that a simple pandoc -s -t html --toc optimade.rst -o optimade.html
produces something serviceable with a few CSS tweaks, though pandoc does not understand the .. comment
syntax we used at the start (it should just be ..
for a block comment according to the rST spec.
Also another thing. Now that we are getting into a bit more of a serious phase: no one knows if GitHub will suddenly change their URL structure. Should we not stop doing these deep-links into GitHub, and instead make sure our released specifications are hosted at permanent links somewhere?
My immediate thought is under the 'schema' repository I just created. But maybe it would be confusing with:
https://schemas.optimade.org/specification/v1.0/optimade.html
although, in a very generalized sense, the specification is a schema (for humans) :-)Did I do a mistake naming that domain 'schemas'? Should it has been something like 'permanent.optimade.org'?...
Originally posted by @rartino in https://github.com/Materials-Consortia/providers/issues/43#issuecomment-653394380