diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..1591b9b --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,47 @@ +name: docs + +on: + push: + branches: ["main"] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install Pandoc + run: sudo apt-get install -y pandoc + + - name: Install Python build dependencies + run: | + python -m pip install --upgrade pip + pip install -r ${{ github.workspace }}/docs/requirements.txt + python3 -m pip install .[opensimplex] + + - name: Build Sphinx documentation + working-directory: ${{ github.workspace }}/docs + run: | + make clean + make html + + - name: Package artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ${{ github.workspace }}/docs/_build/html + + deploy: + needs: build + permissions: + pages: write + id-token: write + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 6b1968a..c7faf32 100644 --- a/.gitignore +++ b/.gitignore @@ -1,14 +1,14 @@ # ignore .vscode settings: .vscode/ -# ignore example directory -examples/perfectworld.tif - # ignore dist directory dist/ -# ignore C++/C library -src/topotoolbox/libtopotoolbox.so - # ingnore tests pycache -tests/__pycache__ \ No newline at end of file +tests/__pycache__ + +# ignore build docs +docs/_build/* + +# ignore _autosummary +docs/_autosummary/* \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..285325e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,31 @@ +# 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 = . +BUILDDIR = _build + +EXAMPLEDIR = ../examples +DOCEXAMPLEDIR = $(SOURCEDIR)/_examples + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Target to build HTML documentation, including copying/removing examples +html: + @echo "Copying examples directory..." + @cp -r $(EXAMPLEDIR) $(DOCEXAMPLEDIR) + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @echo "Cleaning up examples directory..." + @rm -rf $(DOCEXAMPLEDIR) + +# 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/docs/README.md b/docs/README.md new file mode 100644 index 0000000..fed538e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,11 @@ +# Generation Sphinx Documentation + +Before being able to generate the Docs, make sure to install all the python dependencies: `pip install -r requirements.txt` and pandoc. However, they can be ignored since they don't lead to any actual issues. To generate the Sphinx documentation HTML page, run the following commands (Linux): + +```bash +cd /path/to/topotoolbox/docs/ +make clean +make html +``` + +then open the `pytopotoolbox/docs/_build/html/index.html` file in your browser. diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..05f9cd2 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,8 @@ +API Documentation +================= + +.. autosummary:: + :toctree: _autosummary + :recursive: + + topotoolbox \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..53c357b --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,64 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +import os +import sys + +import sphinx_book_theme + +import topotoolbox + + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.napoleon', + 'sphinx.ext.viewcode', + 'sphinx.ext.todo', + 'nbsphinx', +] + +project = 'TopoToolbox' +copyright = '2024, TopoToolbox Team' +author = 'TopoToolbox Team' +release = '3.0.1' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_book_theme' +html_static_path = ['_static'] +html_logo = 'logo.png' + +html_context = { + "default_mode": "light", +} + +# -- Options for nbsphinx ---------------------------------------------------- + +nbsphinx_allow_errors = True + +# -- Options for autodoc ----------------------------------------------------- + +autodoc_default_options = { + 'members': True, + 'undoc-members': True, + 'private-members': False, + 'special-members': '__init__', + 'inherited-members': True, + 'show-inheritance': True, +} + +autosummary_generate = True # Enable autosummary to generate stub files diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..4b53a1b --- /dev/null +++ b/docs/examples.rst @@ -0,0 +1,8 @@ +Examples +======== + +.. nbgallery:: + /_examples/test_genGrid + /_examples/test_GridObject + /_examples/test_load_dem + /_examples/example_magic_funcs diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..c90419e --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +Welcome to TopoToolbox's python documentation! +============================================== + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + Installing + Tutorial + Examples + API + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` \ No newline at end of file diff --git a/docs/installing.rst b/docs/installing.rst new file mode 100644 index 0000000..96f6c49 --- /dev/null +++ b/docs/installing.rst @@ -0,0 +1,80 @@ +How to install +============== + +Generating/Installing distribution archives +------------------------------------------- + +For any operating system, install the following: + +- **Python** +- **pip** +- **Git** (only when *building* the package yourself) + +Linux +~~~~~ + +**Installing from .whl file** + +Make sure to choose the appropriate file for your OS. For Linux, the file name should contain something like: `linux_x86_64` + +.. code-block:: bash + + pip install dist_name.whl + +**Installing directly from the repository:** + +.. code-block:: bash + + cd path/to/pytopotoolbox + pip install . + +**Generating distribution archives** + +.. code-block:: bash + + cd path/to/pytopotoolbox + python3 -m pip install --upgrade build + python3 -m build + +Windows +~~~~~~~ + +**Installing from .whl file** + +Make sure to choose the appropriate file for your OS. For Windows, the file name should contain something like: `win_amd64`. + +.. code-block:: bash + + pip install dist_name.whl + +**Installing directly from the repository:** + +Since there are C/C++ files that need to be compiled in order to build the package, there are a few extra steps to take. + +1. Install the `Developer Command Prompt for VS 2022 `_. + - Scroll down to '*All Downloads*' + - Open '*Tools for Visual Studio*' + - Download '*Build Tools for Visual Studio 2022*' + - Install it while including the '*Desktop development with C++*' workload +2. To ensure the compiler is working with 64-bit architecture, that is necessary for python, **open 'x64 Native Tools Command Prompt for VS 2022'** instead of the '*Developer Command Prompt*' that defaults to 32-bit architecture. +3. In the newly opened terminal, run: + + .. code-block:: bash + + cd path\to\pytopotoolbox + pip install . + +**Generating distribution archives** + +Open the 'x64 Native Tools Command Prompt for VS 2022' Terminal and run: + +.. code-block:: bash + + cd path\to\pytopotoolbox + py -m pip install --upgrade build + py -m build + +Mac +~~~ + +*work in progress* diff --git a/docs/logo.png b/docs/logo.png new file mode 100644 index 0000000..7c96d3d Binary files /dev/null and b/docs/logo.png differ diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +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/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..258508e --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +Sphinx==7.3.7 +sphinx-book-theme==1.1.2 +nbsphinx==0.9.4 +notebook==7.0.5 +jupyter==1.0.0 \ No newline at end of file diff --git a/docs/tutorial.rst b/docs/tutorial.rst new file mode 100644 index 0000000..56a1c18 --- /dev/null +++ b/docs/tutorial.rst @@ -0,0 +1,18 @@ +Tutorial +======== + +Introduction +------------ + +Installing +---------- + +First steps +----------- + +Using the provided examples +--------------------------- + +Using API documentation +----------------------- + diff --git a/examples/example_magic_funcs.ipynb b/examples/example_magic_funcs.ipynb index 2820f54..8045d3f 100644 --- a/examples/example_magic_funcs.ipynb +++ b/examples/example_magic_funcs.ipynb @@ -1,5 +1,12 @@ { "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## example magic functions" + ] + }, { "cell_type": "code", "execution_count": null, diff --git a/examples/test_GridObject.ipynb b/examples/test_GridObject.ipynb index 9219850..4b224c1 100644 --- a/examples/test_GridObject.ipynb +++ b/examples/test_GridObject.ipynb @@ -1,5 +1,12 @@ { "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## test GridObject" + ] + }, { "cell_type": "code", "execution_count": null, diff --git a/examples/test_genGrid.ipynb b/examples/test_genGrid.ipynb index 69dd232..6b828f9 100644 --- a/examples/test_genGrid.ipynb +++ b/examples/test_genGrid.ipynb @@ -1,5 +1,12 @@ { "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## test_genGrid" + ] + }, { "cell_type": "code", "execution_count": null, diff --git a/examples/test_load_dem.ipynb b/examples/test_load_dem.ipynb index a77807c..47705b1 100644 --- a/examples/test_load_dem.ipynb +++ b/examples/test_load_dem.ipynb @@ -1,12 +1,10 @@ { "cells": [ { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "metadata": {}, - "outputs": [], "source": [ - "import topotoolbox as topo" + "## test load dem" ] }, { @@ -15,7 +13,7 @@ "metadata": {}, "outputs": [], "source": [ - "print(topo.get_dem_names())" + "import topotoolbox as topo" ] }, { @@ -24,8 +22,7 @@ "metadata": {}, "outputs": [], "source": [ - "dem = topo.load_dem(\"taiwan\")\n", - "dem.info()" + "print(topo.get_dem_names())" ] }, { @@ -34,17 +31,16 @@ "metadata": {}, "outputs": [], "source": [ + "dem = topo.load_dem(\"taiwan\")\n", + "dem.info()\n", "print(topo.get_cache_contents())" ] }, { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "metadata": {}, - "outputs": [], "source": [ - "topo.clear_cache()\n", - "print(topo.get_cache_contents())" + "Run topo.clear_cache() do remove all files in the TopoToolbox cache." ] } ],