Diagrams_in_doc

[philippemiron]

I will let you add some text and/or move those around. But here is a good start for #251.

[selipot]

@philippemiron How can I see the rendering of these changes?

[philippemiron]

You need to build the docs locally, the instructions are also here.

cd clouddrift/docs

conda install sphinx
pip install sphinx_book_theme
pip install sphinx-copybutton

make html

Then you can open clouddrift/docs/_build/html/index.html in a browser.

[selipot]

Thanks @philippemiron I feel you told me that before

[philippemiron]

No worries.

[milancurcic]

Thanks for this PR, great addition.

[milancurcic]

It has not occurred to me that, as @selipot just pointed out on our call, that having the RST code to insert an image in the Python docstring itself is unfriendly to users reading the docstring from the Python prompt. This is probably why Philippe attempted to place them in api.rst, though that didn't render the images for me. Let's find a way to include graphics in the function docs without polluting the docstring itself, perhaps by looking at how other projects do this (maybe Xarray? not sure).

[philippemiron]

I'm not sure why it's not rendering on your end, but it's working fine for me. See,

[philippemiron]

and I agree (I missed the previous commits) that we don't want to have this in the docstrings of the functions itself.

[milancurcic]

I'm not sure why it's not rendering on your end, but it's working fine for me. See,

I either initially did something wrong or I didn't scroll down enough to see them because they appear at the bottom of the chunk docs. All good, I reverted, this is the way to go.