chore: add QuickStart section #171
Conversation
There was a problem hiding this comment.
How that this work? this will be available also for the user when they are going to the website?
There was a problem hiding this comment.
As far as I tested the notebook is not dynamic since you cannot run anything I don't think those files (the .nc and .txt are useful at all)
There was a problem hiding this comment.
Nope, the .nc files and the .txt are needed to run the notebook. Then, I thought that if we wanted to update it, it would be better to have it there and not have to think 'Where did I save the files that I needed?'
It is for ease of use for ourselves, but of course if you prefer not having them there it is also an option.
There was a problem hiding this comment.
Ok nice :D
Let's keep it in some data folder or something then :D
doc/usage/quickstart.rst
Outdated
| Quick start | ||
| ================= | ||
|
|
||
| Under construction ... | ||
| .. toctree:: | ||
| :maxdepth: 2 | ||
| :caption: Contents: | ||
|
|
||
| .. image:: ../_static/under_construction.gif | ||
| :align: center | ||
| ../_static/notebooks/CMT-english |
There was a problem hiding this comment.
You should treat the notebook directly as page of the website! so basically, you the notebook would be the quickstart page! here you are creating a subsection but there is no need
There was a problem hiding this comment.
Mmh okey, that would make sense too!
There was a problem hiding this comment.
I think there's quite a lot to talk about for the notebook:
- Please apply what we talked about: insitu plots not with curves but with points
- About the insitu plot, what is DOXY? We need to understand/explain the results of the commands
- I think the whole think can be reshaped to be more straight to the point and with better explained use cases (more like: what is I want the most recent data or to download a whole dataset). It's still missing some motivation I feel like.
- It needs to be rerun with the latest version (this can actually be a problem, maybe we could think of a solution to automate it)
Let's make it look a bit more like this: https://docs.xarray.dev/en/stable/getting-started-guide/quick-overview.html (maybe with more explanation and story but yeah)
Once all of this points are covered I will review it again
There was a problem hiding this comment.
- It was explicitly written down to be a line, that's why I was reluctant to change it. I asked and effectively it seems like it would be more correct to write it with points.
- DOXY stands for Dissolved OXYgen (I understand), but definitely not self-explainable. I lack a bit of knowledge on the INSITU part so it is a bit more difficult for me to be able to explain it, but we could take a look.
- Mmh I actually don't dislike that it is a little bit more pragmatic (and with less story telling). I mean, when doing a presentation I'm definitely on your side that greater story telling would be best and use it as the main focus and not as an excuse. In the QuickStart page, though, I feel like something like what it is now is a little in between from the xarray notebook you mention and the good 'story telling' notebook.
- Yep, didn't thought about it (I knew it had to be rerun but not thought that it would need to be rerun precisely before releasing) -> we would need to make something about it.
I like the xarray example!
There was a problem hiding this comment.
- ok let's change it
- Let's try to explain a bit more
- agreed
- yeah well it's not worse than keeping the documentation up to date even if we cannot make it automatic
renaudjester
force-pushed
the
add-notebook
branch
from
7a6e3b2 to
25378eb
Compare
doc/usage/quickoverview.ipynb
Outdated
| "\n", | ||
| "For more information, see the [page about subset](subset-page) of the documentation. You can also check the dedicated pages for the [command line interface](cli-subset) or the {func}`python interface <copernicusmarine.subset>`.\n", | ||
| "\n", | ||
| "The subset is a powerful tool that allow you to benefit from the power the Copernicus Marine services. Indeed, not only do you have access to the whole catalogue but you also can pinpoint the data that interest you thanks to the two services: \"arco-geo-series\" and \"arco-time-series\". They are respectively optimised for retieving maps (short time spam, wide area) and time series (long time span, small area). " |
doc/usage/quickoverview.ipynb
Outdated
| "source": [ | ||
| "## Copernicus Marine toolbox - Subset\n", | ||
| "\n", | ||
| "For more information, see the [page about subset](subset-page) of the documentation. You can also check the dedicated pages for the [command line interface](cli-subset) or the {func}`python interface <copernicusmarine.subset>`.\n", |
There was a problem hiding this comment.
the difference in the 'output' or how the two functions are presented might be a little weird, but for me it works. Just to keep it in mind.
README.md
Outdated
| @@ -86,7 +86,7 @@ Commands: | |||
|
|
|||
| ## Python package (API) | |||
|
|
|||
| The `copernicusmarine` exposes a Python interface to allow you to [call commands as functions](https://toolbox-docs.marine.copernicus.eu/). | |||
| The `copernicusmarine` exposes a python interface to allow you to [call commands as functions](https://toolbox-docs.marine.copernicus.eu/). | |||
There was a problem hiding this comment.
I think python needs to always be with capital P 🤔
There was a problem hiding this comment.
If it's not the case in the rest of the documentation we need to change this
There was a problem hiding this comment.
Mmh python maybe yes, but I looked at how python interface was written in the code and it was the only instance with capital letter. I tried to keep the code consistent.
But if it is better expressed with capital letters I can change the whole code too (doesn't have that many instances).
Co-authored-by: renaudjester <[email protected]> Adding an overview notebook for users to have something to start on to code with the toolbox.
Co-authored-by: renaudjester <[email protected]> Adding an overview notebook for users to have something to start on to code with the toolbox.
Reusing a notebook that we used for a presentation to have a QuickStart, with basic examples of usage and main tasks!