search

FDSN / miniSEED3

https://docs.fdsn.org/projects/miniseed3/
8 stars 3 forks source link

extract docs from json schema file #20

Open crotwell opened 1 year ago

crotwell commented 1 year ago

Need to pull docs from json schema into rst.

Related to changing the documentation of extra headers: I realized that the canonical documentation for each field is not displayed in the specification proper. This document exists, as I think it should, in the JSON schema itself. I had not settled on how to beat render this in the spec. but am working on it (volunteers welcome!).

crotwell commented 1 year ago

Possibility to use https://pypi.org/project/jsonschema2rst/

chad-earthscope commented 1 year ago

For completeness, there another option proposed is to use: https://pypi.org/project/json-schema-for-humans/0.14.1/

chad-earthscope commented 1 year ago

Added the JSFH solution to the draft branch with 64d1225b09966af3b6b651fe01e79f0b7df7f246

crotwell commented 1 year ago

@chad-earthscope , mostly for deployment, but jsfh generates html that has dependencies on google fonts and javascript from jquery, bootstrapcdn, etc. To future-proof this, perhaps these should be hosted locally on fdsn.org? Someone would have to remember to update the html whenever regenerated unless there is an automated way to do this.

To be honest, the html looks kind of weird in that there is an <html> tag inside the main <html> tag, ie looks like file is just copy/pasted by sphinx. It currently displays ok as far as I can tell, but...

chad-earthscope commented 1 year ago

@chad-earthscope , mostly for deployment, but jsfh generates html that has dependencies on google fonts and javascript from jquery, bootstrapcdn, etc. To future-proof this, perhaps these should be hosted locally on fdsn.org? Someone would have to remember to update the html whenever regenerated unless there is an automated way to do this.

Hhmm, that's not ideal in terms of dependencies but it is quite normal in terms of web technologies. Mitigating this by hosting the dependencies on fdsn.org is not an insignificant maintenance issue, and in my opinion more than negates the advantages of using "out of the box" solutions.

To be honest, the html looks kind of weird in that there is an tag inside the main tag, ie looks like file is just copy/pasted by sphinx. It currently displays ok as far as I can tell, but...

Yeah, it's generated HTML that is inserted with a raw include. I also think that's "normal"

chad-earthscope commented 1 year ago

I discovered an issue related to the generated documentation with JSFW: it is not included in the rendered PDF. Quite unfortunate.

One possibility is to use the "flat" template for JSFH, which I believe does not require JS, so reducing that dependency, and it may then render. This also means a user cannot collapse/expand or get "emphasis" when visiting link to a specific section.

crotwell commented 1 year ago

One possibility is to use the "flat" template for JSFH, which I believe does not require JS, so reducing that dependency, and it may then render. This also means a user cannot collapse/expand or get "emphasis" when visiting link to a specific section.

Could we use the flat template to generate a PDF hosted on fdsn.org and use the existing to generate html for readthedocs ? Having a pdf just for long term stability would be desirable as well.

chad-earthscope commented 1 year ago

Well crud. JSFW's "flat" template does not allow the HTML-rendered FDSN Reserved Extra Headers to be included in a PDF.

crotwell commented 1 year ago

Worth revisiting jsonschema2rst? It outputs rst, which hopefully would be pdf friendly in sphinx?

To make it look nice probably requires more work from us to customize, but maybe I can look at it in the next week or two...