search

Materials-Consortia / OPTIMADE

Specification of a common REST API for access to materials databases
https://optimade.org/specification
Creative Commons Attribution 4.0 International
83 stars 37 forks source link

Host specification on optimade.org #347

Open CasperWA opened 3 years ago

CasperWA commented 3 years ago

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

merkys commented 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.

rartino commented 3 years ago

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.)

ml-evs commented 3 years ago

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.