Issue 7 add sphinx doc

.github/workflows/doc.yml

@@ -0,0 +1,42 @@
+name: Build-sphinx-doc
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[doc]
+          pip install ghp-import
+
+      - name: Build HTML
+        env:
+          TOKEN: ${{ secrets.TOKEN }}
+        run: |
+          sed -i '/nb_execution_mode = "off"/d' doc/source/conf.py # enable executing jupyter notebook
+          sphinx-build -W doc/source doc/build/html
+
+      - name: Remove ampersand encoding and token in the generated html
+        run: |
+          # See issues about ampersand encoding at https://github.com/executablebooks/MyST-Parser/issues/760
+          sed -i 's/amp;//g' doc/build/html/Tutorial/Oceans_3.0_API_Tutorial.html
+          # Some cell outputs in the Jupyter notebook contain the token
+          sed -i 's/token=[a-zA-Z0-9-]\+/token=YOUR_TOKEN/g' doc/build/html/Tutorial/onc_Library_Tutorial.html
+
+      - name: Run ghp-import to generate GitHub Pages
+        run: |
+          ghp-import -npfo doc/build/html

.gitignore

@@ -150,3 +150,6 @@ dmypy.json
 
 # commit-msg hook
 commit-msg
+
+# Mac OS specfic
+.DS_Store

CONTRIBUTING.md

@@ -6,23 +6,29 @@ All contributions are welcome and appreciated! Credits will be given in the chan
 
 ### Report Bugs
 
-Bugs can come from Oceans 3.0 API (backend) or the onc library. When reporting an issue, please include some descriptions (code snippet, expected behavior, actual behavior, etc.) to help us reproduce the bug.
+Bugs can come from Oceans 3.0 API (backend) or the onc library.
+When reporting an issue, please include some descriptions
+(code snippet, expected behavior, actual behavior, etc.) to help us reproduce the bug.
 
-Bugs from the backend can also be reported at [Oceans 3.0 Data Portal](https://data.oceannetworks.ca/DataPreview) from the request support form located in the top-right corner.
+Bugs from the backend can also be reported at [Oceans 3.0 Data Portal](https://data.oceannetworks.ca/DataPreview)
+from the request support form located in the top-right corner.
 
 ### Fix Bugs / Implement Features
 
-These are issues labeled with "bug" / "enhancement". Any issue that has no assignee is open to whoever wants to implement it.
+These are issues labeled with "bug" / "enhancement".
+Any issue that has no assignee is open to whoever wants to implement it.
 
 ### Write Documentation
 
-Documentations are important for users to understand the library. You are welcome to raise an issue if you find something that is outdated or can be improved.
+Documentation is important for users to understand the library.
+You are welcome to raise an issue if you find something that is outdated or can be improved.
 
-For docstring, [numpy style](https://numpydoc.readthedocs.io/en/latest/format.html) is used.
+For docstring, the [numpy style](https://numpydoc.readthedocs.io/en/latest/format.html) is used.
 
 ### Commit
 
-We use [conventional commits](https://www.conventionalcommits.org/) for commit messages. Most of the time it is as simple as adding a type before the message.
+We use [conventional commits](https://www.conventionalcommits.org/) for commit messages.
+Most of the time it is as simple as adding a type before the message.
 
 The general format is as follows:
 
@@ -54,7 +60,9 @@ Here is a setup for the local development.
 
 ### Creating a virtual environment
 
-Make sure the python version meets the minimum version requirement defined in pyproject.toml. This step can be simplified if you are using [VS Code](https://code.visualstudio.com/docs/python/environments) or [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html#python_create_virtual_env).
+Make sure the Python version meets the minimum version requirement defined in pyproject.toml.
+This step can be simplified if you are using [VS Code](https://code.visualstudio.com/docs/python/environments)
+or [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html#python_create_virtual_env).
 
 ```shell
 # Create a virtual environment
@@ -108,7 +116,8 @@ or [PyCharm](https://www.jetbrains.com/help/pycharm/pytest.html#run-pytest-test)
 
 ### Formatter
 
-Code is formatted using [black](https://black.readthedocs.io/en/stable/) and [isort](https://pycqa.github.io/isort/).
+The code is formatted using [black](https://black.readthedocs.io/en/stable/)
+and [isort](https://pycqa.github.io/isort/).
 
 ```shell
 $ black src tests
@@ -118,7 +127,7 @@ $ isort src tests
 Or use tox
 
 ```shell
-$ tox -e format
+$ tox -e format # This also formats doc folder
 ```
 
 ### Linter
@@ -149,14 +158,80 @@ $ tox -e lint -- --fix src tests
 
 ## Set up a development environment for documentation
 
-WIP.
+[Sphinx](https://www.sphinx-doc.org) is used for documentation, with several extensions.
+
+- [MyST](https://myst-parser.readthedocs.io): Parse markdown files.
+- [MyST_NB](https://myst-nb.readthedocs.io): Compile jupyter notebooks.
+- [AutoAPI](https://sphinx-autoapi.readthedocs.io/): Auto generate API documentation.
+- [napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html): Support NumPy style docstrings.
+- [viewcode](https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html): Add links to source code.
+- [copybutton](https://sphinx-copybutton.readthedocs.io/): Add a copy button for code blocks.
+
+### Creating a virtual environment for documentation
+
+Follow the same step in "Set up a development environment",
+and install dependencies for _doc_ instead of _dev_.
+
+```shell
+# Install onc library and doc dependencies in editable mode
+$ pip install -e .[doc]
+```
+
+### Building doc
+
+```shell
+$ sphinx-build -W doc/source doc/build/html
+```
+
+`-W` makes the build stop at the first warning.
+Another useful flag is `-E`, which forces rebuilding the structure caching all references completely.
+
+There is a Sphinx extension called [sphinx-autobuild](https://github.com/executablebooks/sphinx-autobuild)
+to watch a Sphinx directory and rebuild the documentation when a change is detected.
+It also includes a live-reload web server.
+
+```shell
+$ sphinx-autobuild -W doc/source doc/build/html --watch "*.md" --watch src
+```
+
+Or use tox
+
+```shell
+tox -e doc-autobuild
+```
+
+### Jupyter notebooks
+
+Jupyter notebooks are formatted using [black](https://black.readthedocs.io/en/stable/).
+
+```shell
+$ black doc
+```
+
+Or use tox
+
+```shell
+$ tox -e format # This also formats src and tests folder
+```
+
+[MyST_NB](https://myst-nb.readthedocs.io) supports executing jupyter notebooks when building the documentation.
+This is turned off in `conf.py` for faster local development and enabled in GitHub Actions.
+Currently, only `onc_Library_Tutorial.ipynb` will be run during the build.
+
+For a better git diff, all the outputs are cleared in the jupyter notebooks.
 
 ## Make a pull request
 
-The GitHub Actions services will automatically run formatter, linter and test suite (_ci.yml_) after you make a pull request.
+The GitHub Actions services will automatically run formatter, linter,
+and test suite (_ci.yml_) after you make a pull request.
 
-Our test uses an Actions secret called TOKEN. For security reasons, GitHub will not pass Actions secrets to workflows that are triggered by a pull request from a fork.
-If you are an outside contributor working on a fork, this means all you checks will fail on the upstream. It will be helpful if you could add an Action secret called TOKEN on your fork, and manually trigger the "Formatting, Linting and Testing" workflow for your feature branch, so we can check the test results on your fork instead of the upstream.
+Our test uses an Actions secret called TOKEN. For security reasons,
+GitHub will not pass Actions secrets to workflows that are triggered by a pull request from a fork.
+If you are an outside contributor working on a fork,
+this means all your checks will fail on the upstream.
+It would be helpful if you could add an Action secret called TOKEN on your fork,
+and manually trigger the "Formatting, Linting and Testing" workflow for your feature branch,
+so we can check the test results on your fork instead of the upstream.
 
 The actual tox environments to run are specified in the [[gh]](https://github.com/tox-dev/tox-gh#basic-example) section of _tox.ini_.
 
@@ -169,37 +244,47 @@ python =
     3.12 = py312
 ```
 
-In the config above, tox will run different set of tox environments on different python versions.
+In the config above, tox will run different sets of tox environments on different Python versions.
 
 - on Python 3.9 job, tox runs `py39` environment,
 - on Python 3.10 job, tox runs `py310`, `format-check` and `lint` environments,
 - on Python 3.11 job, tox runs `py311` environment,
 - on Python 3.12 job, tox runs `py312` environment.
 
-_ci.yml_ uses a matrix strategy for operating systems, so for each python version, it will run three times for Windows, Ubuntu and Mac OS.
+_ci.yml_ uses a matrix strategy for operating systems.
+So for each Python version, it will run three times for Windows, Ubuntu, and Mac OS.
 
 ### Before making a pull request
 
 It is recommended to
 
-1. Incorporate other people's changes from main.
+1. Incorporate other people's changes from _main_.
 
 ```shell
 # Sync the main first if you are on a fork.
 $ git fetch
 $ git rebase origin/main
 ```
 
-2. Install the minimum python version specified in _pyproject.toml_ and run `tox`. This will run environments defined in `env_list` in _tox.ini_.
+2. Install the minimum Python version specified in _pyproject.toml_ and run `tox`.
+   This will run environments defined in `env_list` in _tox.ini_.
 
 ```shell
 $ tox
 ```
 
-3. If you are working on a fork, add an Actions secret called TOKEN, and manually trigger the the "Formatting, Linting and Testing" workflow for your feature branch after pushing your commits.
+3. If you are working on a fork, add an Actions secret called TOKEN,
+   and manually trigger the "Formatting, Linting and Testing" workflow for your feature branch
+   after pushing your commits.
+
+4. If you make changes to any jupyter notebooks, make sure to clear all the outputs and run `$ black doc`.
 
 ### After making the pull request
 
 If you find that some GitHub checks failed, you can check the log in the Actions tab to see what went wrong.
 
-Since a successful test run relies on both the backend and the client library, if your local `tox` run passed but GitHub Action checks failed, it's probably because some temporary issues have happened to our backend server (especially with 500 server error). You can have confidence in your commit and rerun the failed jobs.
+Since a successful test run relies on both the backend and the client library,
+if your local `tox` run passed but GitHub Action checks failed,
+it's probably because some temporary issues have happened to our backend server
+(especially with a 500 server error).
+You can have confidence in your commit and rerun the failed jobs.