add link to API documentation

[ltalirz]

So far, optimade.org is very much developer facing.
After the paper is published, the web site will need to point users in
the right direction.

This is a first step towards this - it's not perfect since the "Try it out" buttons won't work.
Still, I think it's the best documentation we currently have.
I'm deleting the link to the Wiki to make space and since it's not used very much.

Mentioning @CasperWA for info

[CasperWA]

Looks good, thanks @ltalirz

Do you know if it's possible to not create a new tab/window, but instead embed it on the page?

[ltalirz]

Do you know if it's possible to not create a new tab/window, but instead embed it on the page?

We could iframe it of course but what would be the benefit?

[ml-evs]

I support this idea, but do we want to do anything about how our docstrings (in rst format as they are mostly directly from the spec) are rendered in swagger?

[ltalirz]

I support this idea, but do we want to do anything about how our docstrings (in rst format as they are mostly directly from the spec) are rendered in swagger?

If that is easily possible, I'm all for it, of course.
Otherwise I would say, even swagger docstrings in rst format is much better than having to read the spec (which is essentially the current alternative for users)

Also mentioning @gmrigna for comment, whom I forgot

[ml-evs]

If that is easily possible, I'm all for it, of course.

It looks like swagger just uses the generated openapi.json file, so writing some script that converts all the descriptions from rst to md is possible, but maybe not a worthwhile use of anyone's time!

[rartino]

That type of conversion shouldn't be difficult, basically one can just filter the text segments through pandoc, e.g.:

cat description.rst | pandoc -f rst -t markdown > description.md

Is there already a script that automatically extracts the relevant text segments out of the main rst file, or were these copy+pasted?

[ltalirz]

Is there already a script that automatically extracts the relevant text segments out of the main rst file, or were these copy+pasted?

There is no main rst file - openapi.json is generated automatically from the python code.

Looking through the openapi.json file, I actually see already a lot of markdown markup in there.

In terms of rst, there are some things like :val: that I'm not familiar with.
@ml-evs Is there a particular reason for using RST in the docstrings?
If markdown is good enough, we could also just switch to using markdown.

Note that one can still use sphinx to build documentation from docstrings written in markdown.

[rartino]

There is no main rst file - openapi.json is generated automatically from the python code.

I meant the specification document since @ml-evs said the docstrings are "mostly directly from the spec". It would be very good not to maintain two sources of documentation if we can. So, to have some form of scripting generating the docstrings automatically out of the specification every time we update formulations in the specification/add new properties, etc., would be a good idea.

From what you are saying, I assume no such scripting is in place. If the python code uses actual python docstrings, I assume there is no simple way to pull them from an external source. This means such a script needs to extract docstrings out of the specification and insert them in the right place in the python file. Does that seem doable?

In terms of rst, there are some things like :val: that I'm not familiar with.
@ml-evs Is there a particular reason for using RST in the docstrings?
If markdown is good enough, we could also just switch to using markdown.

As he said, they are taken directly from the specification document.

The :val: markup explains what type of literal a literal is (e.g., so you can use different formatting when typesetting them). If you run it through pandoc, they are dropped (since markdown does not support that feature).

[ltalirz]

I meant the specification document since @ml-evs said the docstrings are "mostly directly from the spec".

Right - sorry I overlooked this. The docstrings coming directly from the spec seems like a valid reason to use RST here.

If the python code uses actual python docstrings, I assume there is no simple way to pull them from an external source. This means such a script needs to extract docstrings out of the specification and insert them in the right place in the python file. Does that seem doable?

Even if one would be able to get this to work somehow it would be very fragile ("mostly" is usually not very easy to implement ;-) ). Let's say that I would not want to have to do this myself.

Short of this, it seems to me that the next best solution is indeed to hook into the generation of the openapi.json and to insert an automatic rst-to-md translator in there.

E.g. one could modify the fastapi.openapi.utils.get_openapi function and then use something like new_desc = pypandoc.convert_text(description, 'md', format='rst').
One caveat is that this requires pandoc - pypandoc includes pandoc only on windows and macos.
A solution could be to do this conversion only when writing the spec to json format, and to add an extra for the pypandoc dependency.

[ltalirz]

I've opened issue Materials-Consortia/optimade-python-tools#184 for improving the appearance of the docstrings - in the meanwhile I suggest we go ahead and merge this.

[CasperWA]

I would suggest to point to the newest stable schema from the spec repo instead of optimade-python-tools.
However, this would of course make it harder to update immediately when we implement conversion from rst to md.

[ltalirz]

I don't remember how this "o" got in but we need to remove it