synchronize docs

[sbillinge]

The current pyobjcryst docs are at https://pyobjcryst.readthedocs.io/en/latest/ and the docs built from the migration branch are at https://www.diffpy.org/pyobjcryst/.

They are not fully synchronized for example, see:

and

and there are probably more differences. I am not so concerned about the different themes, and so how different they look, but the content and the laoyout. I am ok with small changes (e.g., installation instructions linked to readme per current group standards) but in other respects, we would like the docs to be a one-to-one drop in replacement.

@zmx27 and @ycexiao please could one of you open the docs side-by-side and go through page by page and synchronize them (except where we don't want to do that). Please reach out if you have questions

[vincefn]

Most importantly we need to keep the notebook examples - in the diffpy migration version they are missing, and I think they are the selling point of the library.

Regarding the theme, I really prefer the pydata sphinx theme if that can be kept.

Also the changelog needs to be updated with the recent changes.

[vincefn]

Also note I added a https://pyobjcryst.readthedocs.io/en/migration/ hidden branch on readthedocs, so it can be checked if it builds correctly (hopefully it gets updated automatically)

[ycexiao]

@zmx27 @sbillinge, I think a lot of synchronization problems are already handled in #64, including Notebook examples, invalid links, and so on. We can start from #64, rename some items according to https://pyobjcryst.readthedocs.io/en/latest/, change the theme, and then we will be ready to go.

[sbillinge]

Thanks @ycexiao I was able to merge #64 now we heard from @vincefn that it is ok to move examples to docs/examples (my preference)

Please can you now work on the last few bits of the synchronization? I am happy to go with the pydata theme. Let's do it for pyobjcryst for now. If we fall in love with it, we can change the theme across the diffpy family.

[vincefn]

Hi - I tried to regenerate the migration pages in rtd, but this ti,e it failed. Here is the raw log.

Again if you have a account on readthedocs I can add you a admin so you can more easily test.

[sbillinge]

Again if you have a account on readthedocs I can add you a admin so you can more easily test.

my rtd username is sbillinge

[vincefn]

my rtd username is sbillinge

You should have received an invite.

[ycexiao]

It is from #67

• remove copied notebook files after the build
• readthedocs is rendering an older version
• QPN notebook is not listed
• Remove "getting started.rst" the documentation template.
• release is not up-to-date.
• main page says "no version found"

[sbillinge]

@ycexiao @zmz27, just two last things to fight with on the docs and we are done. The first one I think should be quick. the second one is a bit more of a fight. If the second one takes too long to fix we can make and issue and do it later. Thanks so much! nearly there!

Only small remaining issue:

• when I regenerate the docs it seems the QPA notebook is not linked from the main page - but it is in the ’notabooks’ page, so not too important
• also, the powder pattern plots are missing e.g. in https://pyobjcryst.readthedocs.io/en/migration/examples/structure-solution-powder-cimetidine.html compared to https://pyobjcryst.readthedocs.io/en/latest/examples/structure-solution-powder-cimetidine.html. I had some issues in the past with this, not sure why it happens. May be due to some nbsphinx issue.

[ycexiao]

The cause for missing plots: Notebook files use interactive widgets to draw figures by default. But it is not well supported in nbsphinx, because nbsphinx generates static HTML.

Compared to the local notebook outcome, https://pyobjcryst.readthedocs.io/en/latest/examples/structure-solution-powder-cimetidine.html also have some missing plots, this also shows that widgets is not very compatible with nbsphinx. I don't know how it manages to render some of the plots, because the web page source is just a link to the notebook file used by nbsphinx-link.

The current fix is to delete code blocks added into the notebook JSON by widgets. It is nearly the same effect as using %matplotlib inline, except pyobjcrst is better designed for widget, so it has cleaner image output. If we replace widget with inline, the web page will be crowded with images generated in the intermediate steps.

@sbillinge, please see if this fix is acceptable. Editing the notebook JSON file does not seem like a good solution.

We can change the output image size via conf.py.

[vincefn]

It is still supposed to work because the notebooks are saved with png previews of the plot (hence the size of the notebooks). I think this is related to the jupyter-lab setting "save widget state automatically". Then, nbsphinx is supposed to re-use the png previews. But I did have some issues in the past with that. I suspect this is related to the version used for rendering with nbsphinx.

If this does not work, I'd let it be for the upcoming release, and I can look into it later. I would not change to %matplotlib inline, because as you said it is much nicer with widgets.