From 425ac7a310fbe1215d8acc2e543f3fe664899859 Mon Sep 17 00:00:00 2001 From: Kan Fu Date: Fri, 26 Jan 2024 16:11:10 -0800 Subject: [PATCH] fix: replace makefile with sphinx-build --- .github/workflows/doc.yml | 3 +- CONTRIBUTING.md | 14 ++----- doc/Makefile | 20 ---------- doc/make.bat | 35 ------------------ .../Tutorial/onc_Library_Tutorial.ipynb | 4 +- doc/source/favicon.ico | Bin 318 -> 0 bytes tox.ini | 2 +- 7 files changed, 9 insertions(+), 69 deletions(-) delete mode 100644 doc/Makefile delete mode 100644 doc/make.bat delete mode 100644 doc/source/favicon.ico diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index 43a5b70..8324d0b 100644 --- a/.github/workflows/doc.yml +++ b/.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: | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5c2cee2..90a153b 100644 --- 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 deleted file mode 100644 index d0c3cbf..0000000 --- a/doc/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/make.bat b/doc/make.bat deleted file mode 100644 index dc1312a..0000000 --- a/doc/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/doc/source/Tutorial/onc_Library_Tutorial.ipynb b/doc/source/Tutorial/onc_Library_Tutorial.ipynb index 6a7f8b0..20b51fe 100644 --- 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 deleted file mode 100644 index dd6f9150c43d97ae468d61999d0e1a4fe38aa71a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 318 zcmZQzU<5(|0RbS%!l1#(z#zuJz@P!d0zj+)#2|58V9!)Zh6|g08LscoWO#9N8N=I$ zI~m?TJ;dRG|NsBEv||zPoH=tEP?%*V5KI8kY3UG}fr&WU*c74; TqMs3D4#*l#uyI%{q(}$=fypyf diff --git a/tox.ini b/tox.ini index 8956131..3398f0f 100644 --- 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 =