fix: replace makefile with sphinx-build

OceanNetworksCanada · Jan 27, 2024 · 1e3f0fb · 1e3f0fb
1 parent a6615a8
commit 1e3f0fb
Show file tree

Hide file tree

Showing 7 changed files with 9 additions and 69 deletions.
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
@@ -27,8 +27,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: |

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -152,24 +152,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

diff --git a/doc/Makefile b/doc/Makefile
diff --git a/doc/make.bat b/doc/make.bat
diff --git a/doc/source/Tutorial/onc_Library_Tutorial.ipynb b/doc/source/Tutorial/onc_Library_Tutorial.ipynb
@@ -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"
    ]
   },
   {

diff --git a/doc/source/favicon.ico b/doc/source/favicon.ico
diff --git a/tox.ini b/tox.ini
@@ -51,7 +51,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 =