Contributing to documentation🦆

Contributing to documentation🦆#

We are using Jupyter Book📙 to build the documentation. The online documentaion is hosted by github pages.

Add/Modify#

Jupyter Book📗 support several different kinds of files as input, including .md files⬇️ .rst files📜, .ipynb files🐍, etc. Executable ones generally requires a slightly different procedures to the narrative files. Here are some instruction on how to work with each of them.

Text files#

Adding files (markdown, reStructuredText, etc) are not very different from contributing code.

  1. Clone the git repository to your local machine

  2. Build the environment. If you do not run this step, the API references and notebooks can not be properly build.

  3. Add or change the files. A useful cheat sheet can be found here: markdown/MyST, reStructuredText. Commit the changes you did along the way.

  4. If you added a new file, in docs/_toc.yml, add the name of your new file in the corresponding location. This tutorial will be helpful, if the file structure is not self-explanatory.

  5. Change directory to seaduck, and run

make docs-build

  1. Go to seaduck/docs/_build/html, you can either open index.html or the html file with the same name to the one that you have made changes to. See if it looks right to you. If not, iterate a little. Send me a message if you need help.

  2. When you are happy with the result, you can tidy things up and make a pull request. After approval, your changes will be deployed.

Notebooks that could be run any where#

As a package that works with oceanographic datasets, almost all the demonstrations requires some supporting data. seaduck provides several datasets available to be downloaded everywhere. It can be accessed simply by

ds = seaduck.utils.get_dataset(name)

Another option is to generate the dataset using mathematical expressions out of thin air. Since this kind of notebook is executed whenever the github action is triggered, it is preferrable that these notebooks run very fast. For example, do not perform heavy calculations in those notebooks and please do not install packages within them.

The procedure is slightly different from that of non-executable files.

  1. Follow step 1 to 6 in the previous section.

  2. Run

make qa

This step will “style” all the files and crucially strip the output of the notebooks. The first time running it is almost certainly going to fail. Don’t worry, pre-commit, the thing under the hood, will automatically fix most of the problems.

Now, run it again. If this time it still has an error, look at the error message and see what you can do. 3. Now, you can tidy things up and make a pull request

Cooler (Sciserver) notebooks#

Cool stuff are not always portable. The ocean 🌊 is an example of that. Say you have something really cool you want to demonstrate, but the dataset it is based on is to large to distribute or it simply takes too long to run. Wouldn’t it be nice if we could have a cloud platform that host a bunch of ocean dataset that is free for everyone to use? It would be even better if the packages I need as an oceanographer is readily installed and I don’t have to worry about a thing. You can use Sciserver! (Am I too dramatic?). Sciserver is also the home base of oceanspy, a package that will make your life so much easier as a oceanographer. After registering on sciserver (you can follow this youtube tutorial here), you can simply call this oceanspy function

import ocenspy as ospy
od = ospy.open_oceandataset.from_catalog('NameOfDataset')
ds = od._ds

Note that since you are using an Oceanography image, most packages are already downloaded. We still need two dependencies just to convert the notebooks.

pip install -U jupyter-book
pip install jupytext

And that’s it, you don’t have to follow the steps of preparing environment.

Now, follow these steps:

  1. Fork and clone this repo adjacent to the seaduck directory

git clone https://github.com/YourGithubNickname/seaduck_sciserver_notebook.git

By “adjacent”, I mean the file structure looks like:

parent_dir
- seaduck
- seaduck_sciserver_notebook

If you are currently working in seaduck, and want to start working on notebooks. You can run

cd ..
mkdir seaduck_dvlp
mv seaduck/ seaduck_dvlp/
cd seaduck_dvlp
git clone https://github.com/YourGithubNickname/seaduck_sciserver_notebook.git

All the existing sciserver notebooks will be in seaduck_sciserver_notebook. If you want to create new ones, put them in there as well.

  1. Have all the fun with your notebooks. However, whenever you plot, always use plt.show().

  2. In seaduck_sciserver_notebook, run the python script

python convert_ipynb.py

This step will add when and which version the notebook was last run on. It will search the file with the string Wenrui Jiang (How egoistic?!), and put the information in the next line. It is a bit ad hoc. If I am not the author of the notebook, simply include: “Wenrui Jiang is a good boy” or something like that after putting your name.

  1. You will realize that the markdown files created may not be able to render properly. This is because the new plots you have are local, but the link we put in the markdown files are what they would look like if the plots are already uploaded. Now, commit all the changes and make a pull request to the seaduck_sciserver_notebook repo. Once the changes are merged into the main branch. Open the file and see if it look as you intended. If so,

cp *.md ../seaduck/docs/sciserver_notebooks/

  1. Change directory back to seaduck. Follow step 4 to 7 in the previous section.

  2. Before the changes are merged, check if the external links work by

make link-check

This check could have some persistent false positive, because some website don’t like link checkers, which is indistinguishable from any other crawler. If you see a bad link, try it in your browser if it works that ignore the warning. If it still does not work, then find the proper link.

Deploy documentation#

https://jupyterbook.org/en/stable/start/publish.html#publish-your-book-online-with-github-pages