Doc fixes for joss review

Makefile

@@ -19,7 +19,7 @@ conda-env-update:
 	$(CONDA) env update $(CONDAFLAGS) -f environment.yml
 
 docs-build:
-	jupyter-book build docs/
+	jupyter-book build docs/ -W --keep-going
 
 joss:
 	pandoc paper/paper.md --bibliography paper/paper.bib -o paper/paper_local.pdf

docs/_config.yml

@@ -1,8 +1,8 @@
 # Book settings
 # Learn more at https://jupyterbook.org/customize/config.html
 
-title: My sample book
-author: The Jupyter Book Community
+title: Seaduck Tutorial
+author: Wenrui Jiang
 logo: logo.png
 
 # Force re-execution of notebooks on each build.
@@ -27,15 +27,13 @@ sphinx:
   config:
     html_theme: sphinx_book_theme
     autodoc_member_order: groupwise
+    html_theme_options:
+      navigation_with_keys: false
     # html_theme_options: {
     #     "relbarbgcolor": 'Orange',
     #     "codebgcolor": 'Coral'
     # }
 
-# Add a bibtex file so that we can create citations
-bibtex_bibfiles:
-- references.bib
-
 # Information about where the book exists on the web
 repository:
   url: https://github.com/MaceKuailv/seaduck  # Online location of your book

docs/_toc.yml

@@ -8,14 +8,16 @@ parts:
     sections:
     - file: one_min_guide
     - file: network_of_object
-  - file: api_reference
+  - file: public_api_reference
     sections:
     - file: api_reference/apiref_OceData.rst
     - file: api_reference/apiref_topology.rst
     - file: api_reference/apiref_eulerian.rst
     - file: api_reference/apiref_lagrangian.rst
     - file: api_reference/apiref_OceInterp.rst
     - file: api_reference/apiref_kernelNweight.rst
+  - file: internal_api_reference
+    sections:
     - file: api_reference/apiref_smartread.rst
     - file: api_reference/apiref_getmasks.rst
     - file: api_reference/apiref_utils.rst
@@ -46,4 +48,5 @@ parts:
     - file: contribute/prep_env
     - file: contribute/contr_cod
     - file: contribute/contr_doc
+    - file: contribute/report_iss
     - file: contribute/tidyNpr

docs/contribute/report_iss.md

@@ -0,0 +1,16 @@
+# Report Issues on GitHub
+
+Aside from contributing to code and documentation, another good way to help the package is to report issues. An Issue could be about a feature request, a bug report, or any of your cool suggestions.
+
+We use GitHub to keep track of the issues. To see a list of all past issues, simply go to [this page](https://github.com/MaceKuailv/seaduck/issues).
+
+Before you report a new issue, make sure you follow these two simple steps:
+
+1. Read through relevant sections in the documentation;
+1. Use the search bar to see if the issue has already been reported.
+
+If both didn't help, you can go ahead and click the big green button that says "New Issue". Writing the issue should be very straightforward. Make sure that the message is clear to other people reading this issue. One of the best ways of doing that is to give a [minimum reproducible example](https://en.wikipedia.org/wiki/Minimal_reproducible_example).
+
+Please remember that the purpose of this GitHub issues channel is to improve the package and that the developers of `seaduck` have their day-time jobs. We are not going to provide direct instruction on how to use this package or python.
+
+That said, never feel intimidated to ask questions that you think is dumb. By reporting an issue, you also help others who are in the same situation. If you spend enough effort working on the problem and still cannot figure it out, there must be something confusing or wrong about the code or the documentation. We will really appreciate it if you point that out.

docs/get_started.md

@@ -2,7 +2,7 @@
 
 For a extremely quick start, read this [one minute guide](./one_min_guide.md). Or, learn about how the objects and functions are related to each other [here](./network_of_object.md).
 
-If you have questions about any function, you can always go to [API references](./api_reference.md). Or you could checkout the following examples. More example can be found [here](ideal_test.md) and [here](ocean_example.md)
+If you have questions about any function, you can always go to [API references](./public_api_reference.md). Or you could checkout the following examples. More example can be found [here](ideal_test.md) and [here](ocean_example.md)
 
 ::::{grid} 1 1 1 3
 :class-container: text-center

docs/how_to_install.md

@@ -6,23 +6,35 @@ The package can be installed simply by
 pip install seaduck
 ```
 
-or, alternatively (not available yet)
+or, alternatively
 
 ```shell
 conda install -c conda-forge seaduck
 ```
 
 or, alternatively (for latest code development), see [a guide for new contibutors](guide_for_developer.md).
 
+## Optional dependencies
+
+- numba
+
+  - Compile and make everything faster!
+
+- matplotlib
+
+  - Plot the shape of interpolation kernel.
+
+- pandas
+
+  - Show variable aliasing in an intuitive way.
+
+- pooch, zarr, cartopy
+
+  - Needed for running the tutorial examples.
+
 ## Required dependencies
 
 - python
 - numpy
 - xarray
-
-## Optional dependencies
-
-- pandas
-- numba
-- matplotlib
 - dask

docs/idealize_test/tilted_stream.ipynb

@@ -1,7 +1,6 @@
 {
  "cells": [
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -42,7 +41,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -84,7 +82,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -123,7 +120,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -143,7 +139,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -177,7 +172,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -216,7 +210,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -235,7 +228,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -273,7 +265,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -325,7 +316,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -354,7 +344,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {
     "tags": [
@@ -387,7 +376,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {
     "tags": [
@@ -399,7 +387,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -428,7 +415,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -457,7 +443,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -467,7 +452,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -484,11 +468,10 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Bu these are pretty small errors!"
+    "But these are pretty small errors!"
    ]
   }
  ],
@@ -509,7 +492,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.4"
+   "version": "3.9.7"
   }
  },
  "nbformat": 4,

docs/internal_api_reference.md

@@ -0,0 +1,11 @@
+# Internal API reference
+
+## utility functions
+
+[smart_read](api_reference/apiref_smartread.rst)
+[get_masks](api_reference/apiref_getmasks.rst)
+[utils](api_reference/apiref_utils.rst)
+
+## Relative coordinate handling
+
+[RelCoord](api_reference/apiref_RelCoord.rst)