fix: replace makefile with sphinx-build

Author: kan-fu

.github/workflows/doc.yml

@@ -28,8 +28,7 @@ jobs:
           TOKEN: ${{ secrets.TOKEN }}
         run: |
           sed -i '/nb_execution_mode = "off"/d' doc/source/conf.py # enable executing jupyter notebook
-          cd doc
-          make html
+          sphinx-build -W doc/source doc/build/html
 
       - name: Remove ampersand encoding and token in the generated html
         run: |

CONTRIBUTING.md

@@ -180,24 +180,18 @@ $ pip install -e .[doc]
 ### Building doc
 
 ```shell
-$ cd doc
-$ make html
-# For Windows, use ".\make html" or "doc\make html" without cd
+$ sphinx-build -W doc/source doc/build/html
 ```
 
-Sometimes you need to clean the build folder to force a rebuild.
-
-```shell
-$ make clean
-# For Windows, use ".\make clean" or "doc\make html" without cd
-```
+`-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 doc/source doc/build/html --watch "*.md" --watch src
+$ sphinx-autobuild -W doc/source doc/build/html --watch "*.md" --watch src
 ```
 
 Or use tox

doc/Makefile

@@ -11,7 +11,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The _onc_ library is developed based on the _requests_ library, which is a popular library for making HTTP requests in Python. In fact, you can use _requests_ alone to interact with the Oceans 3.0 API. But there are cases when you will find the _onc_ library very handy to use (boolean parse, one-click data product download, ability to automatically download all pages, etc.). The tutorial will demonstrate both versions.\n"
+    "The _onc_ library is developed based on the _requests_ library, which is a popular library for making HTTP requests in Python. In fact, you can use _requests_ alone to interact with the Oceans 3.0 API. But there are cases when you will find the _onc_ library very handy to use (boolean parse, one-click data product download, ability to automatically download all pages, etc.). The tutorial will demonstrate both versions.\n",
+    "\n",
+    "This is a Jupyter notebook. You can download the file [here](https://github.com/OceanNetworksCanada/api-python-client/blob/main/doc/source/Tutorial/onc_Library_Tutorial.ipynb).\n"
    ]
   },
   {

doc/make.bat

@@ -50,7 +50,7 @@ deps =
     sphinx-autoapi
     sphinx_copybutton
     sphinx_rtd_theme
-commands = sphinx-autobuild doc/source doc/build/html --watch "*.md" --watch src
+commands = sphinx-autobuild -W doc/source doc/build/html --watch "*.md" --watch src
 
 [gh]
 python =