Docs reorganise - #386
Merged
Merged
Docs reorganise#386
Conversation
…ument column entries are consistent
for more information, see https://pre-commit.ci
j-atkins
marked this pull request as ready for review
September 17, 2026 14:32
erikvansebille
left a comment
erikvansebille
left a comment
Member
There was a problem hiding this comment.
New docs looks great!! Some feedback below
| From here, you should replace any references to `EXPEDITION_NAME` with the actual name you used for your expedition when running any `virtualship` commands. | ||
| ``` | ||
|
|
||
| <!-- TODO: some of this detail will change when [#362](https://github.com/Parcels-code/virtualship/issues/362) is implemented --> |
| ### Waypoint datetimes | ||
|
|
||
| ```{note} | ||
| VirtualShip supports running experiments in the years 1993 through to the present day by leveraging the suite of products available on the Copernicus Marine Data Store. |
Member
There was a problem hiding this comment.
Make this a link to Copernicus Marine Data Store?
| - Deploying Argo Floats or CTDs at waypoints which are far apart in space and/or time will require more RAM than deploying them at waypoints which are closer together. | ||
| - If experiencing issues with termination during simualtion, consider reducing the number of waypoints and/or the distance between waypoints. | ||
| - Note, you can likely keep less intensive instruments (e.g. Drifters, ADCP) running at more distant waypoints. The software will recognise that CTDs/Argo Floats are not being deployed at these waypoints and will not inflate the data retrieval for these instruments uncessarily in this case. | ||
| - If you are running VirtualShip in the pre-configured GitHub Codespaces environment, the more [powerful option](../tutorials/codespaces_guide.md/#spinning-up-a-more-powerful-codespace) (4 cores, 16GB RAM) should be able to handle most expedition deployments. This is a useful option if you are experiencing issues with the standard Codespaces configuration (2 cores, 8GB RAM). |
Member
There was a problem hiding this comment.
Mention it comes at a cost?
Member
There was a problem hiding this comment.
Good addition, but I'm not sure you should mention an explicit amount of hours. That could be changed in the future by GitHub without us knowing. I would simply say the hours would be halved
| From here you can carry on your analysis. In general, we encourage you to use [Parcels](https://Parcels-code.org/) (i.e. `parcels.read_particlefile()`) to read in VirtualShip output files, and tools such as [Polars](https://www.pola.rs/) and/or [Pandas](https://pandas.pydata.org/) for further data analysis. We also provide various further [VirtualShip tutorials](https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/index.html) which provide examples of how to visualise data recorded by the VirtualShip instruments. Use these to help you get started! | ||
|
|
||
| ```{tip} | ||
| We also host a [Binder](https://mybinder.org/) environment (note this is separate to the GitHub Codespaces workspace you may be using) with all the necessary post-processing tools pre-installed and all the tutorials ready to use. This might be useful as a means to explore your data at first. See [here](../tutorials/binder_workspace.md) for more detail or await further instruction from your instructor. |
Member
There was a problem hiding this comment.
Make the binder link to our actual environment directly?
| If you want to do more extensive analysis, we recommend that you download your data and results to your own computer, and run the analysis there. You will also need to install the required dependencies to your own computer. | ||
|
|
||
| ```{tip} | ||
| A full list of dependencies is provided in the [environment.yml](https://github.com/j-atkins/virtualship-workspace/blob/main/.binder/environment.yml) file in the VirtualShip Workspace repository. You can use this file to install the dependencies on your own computer (e.g. with the `conda` [package manager](https://anaconda.org/channels/anaconda/packages/conda/overview)). |
Member
There was a problem hiding this comment.
Again, change link to a Parcels-Code org repo?
|
|
||
| ## 2) Launch the VirtualShip Workspace via GitHub Codespaces | ||
|
|
||
| <!-- TODO: replace eventually with the Parcels-code hosted repo --> |
Member
There was a problem hiding this comment.
Any idea when "eventually" is?
| - This tool is used to plan the expedition route and generate the coordinates for the VirtualShip protocol. | ||
| - It is an authentic tool used by real-life oceanographers to plan their research expedtions, and is a good example of the type of software that students may encounter in their future careers. | ||
| - There is no sign-up required to use the tool, but students may need some time to get familiar with it. | ||
| - As mentioned in the guides, the `VirtualShip` software can ingest exported coordinate files straight from MFP. |
Member
There was a problem hiding this comment.
Add a link to the relevant guide(s)?
|
|
||
| #### Pre-configured post-processing workspace | ||
|
|
||
| We also host a VirtualShip post-processing environment via [Binder](https://mybinder.org/), which is a cloud-based JupyterLab environment. This can be used to run the example tutorials and any other analysis code that students may wish to write, without having to install anything on their own devices. All relevant dependencies are pre-installed in this environment, the example tutorials are directly available in the workspace, and the VirtualShip output files can be uploaded to the environment for analysis. |
Member
There was a problem hiding this comment.
Again, link directly to the relevant binder page?
Member
There was a problem hiding this comment.
should we also make sure that this page is directly accessible from https://virtualship.parcels-code.org/#getstarted-researcher?
Collaborator
Author
There was a problem hiding this comment.
Yes I think so, I will make an issue in the VirtualShip Website repo
erikvansebille
approved these changes
Sep 18, 2026
erikvansebille
left a comment
erikvansebille
left a comment
Member
There was a problem hiding this comment.
One final comment (about not mentioning specific amount of compute hours on GitHub) - otherwise good to go
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR performs a major reorganisation of the docs, to be more in line with the VirtualShip website structure of funnelling visitors into Learner, Educator, Researcher, Developer user profiles.
Therefore, this PR primarily targets the "User Guide" section of the docs, now with four buttons taking users to each of the pages dedicated to the different user profiles. The Educator guide is pretty complete now that we've been using it in recent train-the-teacher sessions, and the Researcher tab now also has content (somewhat generic but meant as a starting point).
Note, the Learner and Developer tabs are currently empty, with placeholders. These will be populated soon/in separate PRs.