RST not rendering with mkdocs

[ml-evs]

The API docs don't seem to render in rst (see e.g. https://www.optimade.org/optimade-python-tools/reference/server/mappers/entries/#optimade.server.mappers.entries.BaseResourceMapper)

Originally posted by @ml-evs in #295 (comment)

[ml-evs]

Thoughts on this @shyamd? I can't see any plugins for mkdocs + rst

[shyamd]

I don't think that's a RST issue, but a formatting issue. It doesn't currently work with numpy docs. So we should reformat for Google Docs.

[ml-evs]

All the model descriptions are written in rst though, as they're taken from the spec...

[shyamd]

The model descriptions actually look pretty good, for instance: https://www.optimade.org/optimade-python-tools/reference/models/entries/ .

The section you linked is from the BaseMapper in the server. That section at the top is just weird text. I'll try and figure out what is going on there.

[ml-evs]

Hmmm, not sure I agree for the more complicated (and important) models, e.g. structure https://www.optimade.org/optimade-python-tools/reference/models/structures/

[shyamd]

Hmm good catch. This is very difficult to fix within the documentation workflow. Mkdocs is in markdown and expects markdown. Typically, docstrings don't themselves contain RST or markdown. The better solution is to change the docstrings.

[ml-evs]

Hmm good catch. This is very difficult to fix within the documentation workflow. Mkdocs is in markdown and expects markdown. Typically, docstrings don't themselves contain RST or markdown. The better solution is to change the docstrings.

Thoughts @CasperWA? This would decouple our description fields from the spec (the only coupling previously is that they were copied and pasted, but presumably some are now out of date...), but a rewrite would also solve #184.

I see two options:

• switch away from mkdocs (boo)
• run the spec through pandoc to get md, then c+p from there once 1.0-rc2 is out?

[CasperWA]

Third option would be to go through and manually update description to markdown...

At this point I'm almost tempted to do that and update the various descriptions at the same time. However, it may make it a bit more difficult going forward if it's not an easy copy-paste from the spec.

[ml-evs]

Third option would be to go through and manually update description to markdown...

At this point I'm almost tempted to do that and update the various descriptions at the same time. However, it may make it a bit more difficult going forward if it's not an easy copy-paste from the spec.

I think this was my option 2!

[CasperWA]

Third option would be to go through and manually update description to markdown...
At this point I'm almost tempted to do that and update the various descriptions at the same time. However, it may make it a bit more difficult going forward if it's not an easy copy-paste from the spec.

I think this was my option 2!

Right. Yeah, okay. I think that would be the nicest to be honest then. And the description of how you would carry it out sounds better than mine as well :)

[ml-evs]

👍

Then let's get the rc2 models up to date with the current description style and then redo all description conversions in one go.