search

Materials-Consortia / optimade-python-tools

Tools for implementing and consuming OPTIMADE APIs in Python
https://www.optimade.org/optimade-python-tools/
MIT License
71 stars 44 forks source link

Adding markdown links to OpenAPI schema #366

Open CasperWA opened 4 years ago

CasperWA commented 4 years ago

I don't know that it's always preceded by "section", but maybe we can create an issue suggesting adding links to the OpenAPI descriptions and leave it for later to not block the release of v1.0.0-rc.2?

Originally posted by @CasperWA in https://github.com/Materials-Consortia/optimade-python-tools/pull/351

As seen in the quote above, I tried implementing this already in #351, however, due to the pressing release of v1.0.0-rc.2 of the OPTIMADE API specification, this addition was considered non-essential and too time consuming to implement in that PR.

Instead it has now become this issue, to track the progress of adding the various hyperlinks.

ml-evs commented 4 years ago

Where should the links go, to the section in the optimade.rst on GH?

ml-evs commented 4 years ago

Also I think we should do this before we make our next PR to the spec repo, which I guess makes this highish priority...

CasperWA commented 4 years ago

Where should the links go, to the section in the optimade.rst on GH?

That was my original intention. However in Materials-Consortia/providers#43 @rartino has suggested to have the specification be hosted outside the github.com domain, which I think makes sense. @rartino mentioned either putting it under the schema.optimade.org sub-domain or possibly another sub-domain, however, I have suggested to host it directly on the optimade.org website (under "API Specification"). Whatever is decided in the issue (or elsewhere), I think we should point the link to the sections in the specification hosted outside the github.com domain. Hence, I would consider this issue blocked, if we don't want to do double work.

Or we could say we don't care, and will link to the github.com-hosted specification and be done with it? :)

Either way, yes, to specific link anchors / sections in the specification was my intention.

ml-evs commented 4 years ago

Hmm, maybe we should wait until that is all set up then!

ml-evs commented 4 years ago

(That all sounds good to me though, whatever is decided)

CasperWA commented 3 years ago

Note, an issue of moving the specification under the optimade.org domain has been created here: Materials-Consortia/OPTIMADE#347.