search

CDAT / cdms

8 stars 10 forks source link

cdms5.pdf documentation was not converted correctly! #319

Open jypeter opened 5 years ago

jypeter commented 5 years ago

Livermore, we have a problem ! @doutriaux1 @dnadeau4

I have to use the getWeight method and I have checked if its documentation was correctly converted, because this is a really useful feature of cdms2, that's probably not available elsewhere (eg netcdf4 ?)

So I went to CDAT web site -> documentation -> cdms -> Search -> getweight, I clicked on the first suggested link 2. CDMS Python Application Programming Interface and used the search field of my browser to look for getweight.

This led me to 2.9.7. RectGrid Methods, Additional to HorizontalGrid Methods

getWeight was indeed mentioned in the text, but something seemed odd, and the documentation seemed to jump from getOrder to setType

I then went to my Dead Sea scrolls vault to open the original and precious cdms5.pdf scroll and I discovered that some of the formatting had not been translated correctly! The information seems to be there, but wrong formatting makes it a bit useless. The vicious thing is that the page looks nice, so you assume everything's OK!

I have also found a slightly similar version of the documentation in https://github.com/CDAT/cdms/blob/master/docs/source/manual/cdms_2.rst, that seems to have the same formatting problem. I dont' know how this page and the readthedoc relate

Things will be clearer if you compare the 2 screenshots below that cover the same text. One from the original pdf documents five methods, and the other from the readthedoc website has the same content with wrong formatting and seems to define only two methods

Original pdf version

GetWeight_frompdf

Readthedoc version

GetWeight_fromreadthedoc

dnadeau4 commented 5 years ago

Thanks! Will fix this today.

dnadeau4 commented 5 years ago

https://cdms.readthedocs.io/en/docstanya2/manual/cdms_2.html

Something has changed in read the docs and my tables are not "align:center".

I had all kind of issues with sphinx as well. I thought it would be easy....

jypeter commented 5 years ago

Be careful, I have had a quick look at your update doc link above and even if getWeight now appears correctly, you'll see that String getType() that should also appear in the Type/Method columns, still appears in the Description column of getOrder!

Same problem with Transient-GenericGrid toGenericGrid(gridid=None) just above, that appears in the Description of toCurveGrid (gridid=None)

I hope you can find a way to automatically correct all the occurences of this type of problem in the documentation, because it will be a nightmare to check it by hand. Especially since it does not look obviously wrong when you have a quick look at the documentation

dnadeau4 commented 5 years ago

@jypeter it has been a nightmare to convert these very large MarkDown table to RST.

dnadeau4 commented 5 years ago

@jypeter thanks for your help with this, we are fixing it.

dnadeau4 commented 5 years ago

I think I got it this time and I add new "align" rules for the readthedocs table. https://cdms.readthedocs.io/en/docstanya2/manual/cdms_2.html#rectgrid-methods-additional-to-horizontalgrid-methods

jypeter commented 5 years ago

I have checked the link above, and I still see an error, compared to the screenshot from the original cdms5.pdf I posted above!

Open https://cdms.readthedocs.io/en/latest/manual/cdms_2.html?highlight=toGenericGrid and then search "toGenericGrid". I mentioned that in my previous comment above

That's "just" an example. I'm afraid there may be other occurrences of this formatting/conversion problem in the rest of the documentation