From 56000c4b36a7393d3e6c3da5b525ed85b432394f Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Fri, 31 May 2024 14:45:21 +0200 Subject: [PATCH 01/24] Add sphinx quickstart --- docs/Makefile | 20 ++++++++++++++++++++ docs/conf.py | 28 ++++++++++++++++++++++++++++ docs/index.rst | 20 ++++++++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++++++++++++ 4 files changed, 103 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# 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 + +# 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/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..cd60010 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,28 @@ +# 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 + +project = 'TopoToolbox' +copyright = '2024, Theotest' +author = 'Theotest' +release = '3.0.1' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [] + +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 = 'alabaster' +html_static_path = ['_static'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..2e87f5b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. TopoToolbox documentation master file, created by + sphinx-quickstart on Fri May 31 14:42:19 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to TopoToolbox's documentation! +======================================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` 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 From 6794e47b321b9e9d4290aed07d86b07785ebc9d4 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Fri, 31 May 2024 14:48:34 +0200 Subject: [PATCH 02/24] Reconfigure sphinx quickstart --- docs/Makefile | 4 ++-- docs/make.bat | 4 ++-- docs/{ => source}/conf.py | 6 +++--- docs/{ => source}/index.rst | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) rename docs/{ => source}/conf.py (89%) rename docs/{ => source}/index.rst (88%) diff --git a/docs/Makefile b/docs/Makefile index d4bb2cb..d0c3cbf 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,8 +5,8 @@ # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build +SOURCEDIR = source +BUILDDIR = build # Put it first so that "make" without argument is like "make help". help: diff --git a/docs/make.bat b/docs/make.bat index 32bb245..747ffb7 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -7,8 +7,8 @@ REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) -set SOURCEDIR=. -set BUILDDIR=_build +set SOURCEDIR=source +set BUILDDIR=build %SPHINXBUILD% >NUL 2>NUL if errorlevel 9009 ( diff --git a/docs/conf.py b/docs/source/conf.py similarity index 89% rename from docs/conf.py rename to docs/source/conf.py index cd60010..c9e8665 100644 --- a/docs/conf.py +++ b/docs/source/conf.py @@ -7,8 +7,8 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = 'TopoToolbox' -copyright = '2024, Theotest' -author = 'Theotest' +copyright = '2024, testname' +author = 'testname' release = '3.0.1' # -- General configuration --------------------------------------------------- @@ -17,7 +17,7 @@ extensions = [] templates_path = ['_templates'] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = [] diff --git a/docs/index.rst b/docs/source/index.rst similarity index 88% rename from docs/index.rst rename to docs/source/index.rst index 2e87f5b..f2c877f 100644 --- a/docs/index.rst +++ b/docs/source/index.rst @@ -1,5 +1,5 @@ .. TopoToolbox documentation master file, created by - sphinx-quickstart on Fri May 31 14:42:19 2024. + sphinx-quickstart on Fri May 31 14:47:30 2024. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. From 083059d5a116000a72341565c7dbdbe778be53e9 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Fri, 31 May 2024 22:20:26 +0200 Subject: [PATCH 03/24] Setup Sphinx docs --- .gitignore | 5 ++- docs/Makefile | 4 +-- docs/{source => }/conf.py | 26 +++++++++++---- docs/{source => }/index.rst | 2 +- docs/make.bat | 4 +-- docs/source/modules.rst | 7 ++++ docs/source/topotoolbox.gridmixins.rst | 45 ++++++++++++++++++++++++++ docs/source/topotoolbox.rst | 37 +++++++++++++++++++++ 8 files changed, 117 insertions(+), 13 deletions(-) rename docs/{source => }/conf.py (66%) rename docs/{source => }/index.rst (88%) create mode 100644 docs/source/modules.rst create mode 100644 docs/source/topotoolbox.gridmixins.rst create mode 100644 docs/source/topotoolbox.rst diff --git a/.gitignore b/.gitignore index 6b1968a..e353646 100644 --- a/.gitignore +++ b/.gitignore @@ -11,4 +11,7 @@ dist/ src/topotoolbox/libtopotoolbox.so # ingnore tests pycache -tests/__pycache__ \ No newline at end of file +tests/__pycache__ + +# ignore build docs +docs/_build/* \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index d0c3cbf..d4bb2cb 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,8 +5,8 @@ # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build +SOURCEDIR = . +BUILDDIR = _build # Put it first so that "make" without argument is like "make help". help: diff --git a/docs/source/conf.py b/docs/conf.py similarity index 66% rename from docs/source/conf.py rename to docs/conf.py index c9e8665..e56025c 100644 --- a/docs/source/conf.py +++ b/docs/conf.py @@ -6,23 +6,35 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information +import os +import sys +import sphinx_book_theme + + +sys.path.insert(0, os.path.abspath('../src/topotoolbox')) + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'sphinx.ext.viewcode', + 'sphinx.ext.todo', +] + project = 'TopoToolbox' -copyright = '2024, testname' -author = 'testname' +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 -extensions = [] - templates_path = ['_templates'] -exclude_patterns = [] - +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 = 'alabaster' +# Specify the theme name +html_theme = 'sphinx_book_theme' html_static_path = ['_static'] diff --git a/docs/source/index.rst b/docs/index.rst similarity index 88% rename from docs/source/index.rst rename to docs/index.rst index f2c877f..e5b623a 100644 --- a/docs/source/index.rst +++ b/docs/index.rst @@ -1,5 +1,5 @@ .. TopoToolbox documentation master file, created by - sphinx-quickstart on Fri May 31 14:47:30 2024. + sphinx-quickstart on Fri May 31 15:35:16 2024. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. diff --git a/docs/make.bat b/docs/make.bat index 747ffb7..32bb245 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -7,8 +7,8 @@ REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) -set SOURCEDIR=source -set BUILDDIR=build +set SOURCEDIR=. +set BUILDDIR=_build %SPHINXBUILD% >NUL 2>NUL if errorlevel 9009 ( diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..3c5692d --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,7 @@ +topotoolbox +=========== + +.. toctree:: + :maxdepth: 4 + + topotoolbox diff --git a/docs/source/topotoolbox.gridmixins.rst b/docs/source/topotoolbox.gridmixins.rst new file mode 100644 index 0000000..3f3dec3 --- /dev/null +++ b/docs/source/topotoolbox.gridmixins.rst @@ -0,0 +1,45 @@ +topotoolbox.gridmixins package +============================== + +Submodules +---------- + +topotoolbox.gridmixins.fillsinks module +--------------------------------------- + +.. automodule:: topotoolbox.gridmixins.fillsinks + :members: + :undoc-members: + :show-inheritance: + +topotoolbox.gridmixins.identifyflats module +------------------------------------------- + +.. automodule:: topotoolbox.gridmixins.identifyflats + :members: + :undoc-members: + :show-inheritance: + +topotoolbox.gridmixins.info module +---------------------------------- + +.. automodule:: topotoolbox.gridmixins.info + :members: + :undoc-members: + :show-inheritance: + +topotoolbox.gridmixins.magic module +----------------------------------- + +.. automodule:: topotoolbox.gridmixins.magic + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: topotoolbox.gridmixins + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/topotoolbox.rst b/docs/source/topotoolbox.rst new file mode 100644 index 0000000..83f52ea --- /dev/null +++ b/docs/source/topotoolbox.rst @@ -0,0 +1,37 @@ +topotoolbox package +=================== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + topotoolbox.gridmixins + +Submodules +---------- + +topotoolbox.grid\_object module +------------------------------- + +.. automodule:: topotoolbox.grid_object + :members: + :undoc-members: + :show-inheritance: + +topotoolbox.utils module +------------------------ + +.. automodule:: topotoolbox.utils + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: topotoolbox + :members: + :undoc-members: + :show-inheritance: From 9d585e5b28bb95f986674ae825aa028ce2899c2f Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Wed, 5 Jun 2024 18:13:29 +0200 Subject: [PATCH 04/24] basic docs page done --- README.md | 11 ++++++ docs/api.rst | 24 +++++++++++++ docs/conf.py | 2 +- docs/index.rst | 15 +++------ docs/logo.png | Bin 0 -> 18046 bytes docs/source/modules.rst | 7 ---- docs/source/topotoolbox.gridmixins.rst | 45 ------------------------- docs/source/topotoolbox.rst | 37 -------------------- 8 files changed, 41 insertions(+), 100 deletions(-) create mode 100644 docs/api.rst create mode 100644 docs/logo.png delete mode 100644 docs/source/modules.rst delete mode 100644 docs/source/topotoolbox.gridmixins.rst delete mode 100644 docs/source/topotoolbox.rst diff --git a/README.md b/README.md index 8c884e1..ea0ceeb 100644 --- a/README.md +++ b/README.md @@ -75,3 +75,14 @@ For any operating system, install the following: ### Mac [work in progress] + +## Generation Sphinx Documentation + +To generate the Sphinx documentation HTML page, run the following commands: + +```bash +cd /path/to/topotoolbox/docs/ +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..6887991 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,24 @@ +API Documentation +================= + +utils +----- + +.. automodule:: topotoolbox.utils + :members: + :undoc-members: + :show-inheritance: + + +grid_object +----------- + +.. automodule:: topotoolbox.grid_object + :members: + :undoc-members: + :show-inheritance: + +.. automodule:: topotoolbox.gridmixins + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/conf.py b/docs/conf.py index e56025c..8063e56 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -35,6 +35,6 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -# Specify the theme name html_theme = 'sphinx_book_theme' html_static_path = ['_static'] +html_logo = 'logo.png' diff --git a/docs/index.rst b/docs/index.rst index e5b623a..43f1105 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,20 +1,15 @@ -.. TopoToolbox documentation master file, created by - sphinx-quickstart on Fri May 31 15:35:16 2024. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to TopoToolbox's documentation! -======================================= +Welcome to TopoToolbox's python documentation! +============================================== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: - + api Indices and tables ================== * :ref:`genindex` * :ref:`modindex` -* :ref:`search` +* :ref:`search` \ No newline at end of file diff --git a/docs/logo.png b/docs/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..7c96d3d5012a1270ed2f5316c1ea0d7caa7f2e5e GIT binary patch literal 18046 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 =R#A+W`Nu8- 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 f%ACO*1~V9TpP6tA4=jPOGB6mCKsr Date: Thu, 6 Jun 2024 15:04:07 +0200 Subject: [PATCH 05/24] added ipynb support to docs --- docs/conf.py | 1 + docs/examples.rst | 4 ++ docs/getting_started.ipynb | 41 ++++++++++++++++++ docs/index.rst | 4 ++ docs/installing.rst | 87 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 137 insertions(+) create mode 100644 docs/examples.rst create mode 100644 docs/getting_started.ipynb create mode 100644 docs/installing.rst diff --git a/docs/conf.py b/docs/conf.py index 8063e56..a4e088f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,6 +18,7 @@ 'sphinx.ext.napoleon', 'sphinx.ext.viewcode', 'sphinx.ext.todo', + 'nbsphinx', ] project = 'TopoToolbox' diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..2940650 --- /dev/null +++ b/docs/examples.rst @@ -0,0 +1,4 @@ +Examples +======== + +Here we can link to the example .ipynb files later on. diff --git a/docs/getting_started.ipynb b/docs/getting_started.ipynb new file mode 100644 index 0000000..539126a --- /dev/null +++ b/docs/getting_started.ipynb @@ -0,0 +1,41 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Getting Started with TopoToolbox" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "import topotoolbox" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.12" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/index.rst b/docs/index.rst index 43f1105..6b0caf7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,10 @@ Welcome to TopoToolbox's python documentation! :caption: Contents: api + installing + getting_started + examples + Indices and tables ================== diff --git a/docs/installing.rst b/docs/installing.rst new file mode 100644 index 0000000..ee2c588 --- /dev/null +++ b/docs/installing.rst @@ -0,0 +1,87 @@ +How to install +============== + +Installing topotoolbox with pip +------------------------------- + +[not working jet!] :: + + $ pip install topotoolbox + +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* From 3c0f7c5ba8318ef525df9f8adb2983808b8e3415 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 10 Jun 2024 19:23:57 +0200 Subject: [PATCH 06/24] changes to notebooks --- docs/examples/example_magic_funcs.ipynb | 157 ++++++++++++++++++ docs/examples/test_GridObject.ipynb | 89 ++++++++++ docs/examples/test_genGrid.ipynb | 70 ++++++++ .../test_load_dem.ipynb} | 33 +++- examples/example_magic_funcs.ipynb | 7 + examples/test_GridObject.ipynb | 7 + examples/test_genGrid.ipynb | 7 + examples/test_load_dem.ipynb | 20 +-- 8 files changed, 375 insertions(+), 15 deletions(-) create mode 100644 docs/examples/example_magic_funcs.ipynb create mode 100644 docs/examples/test_GridObject.ipynb create mode 100644 docs/examples/test_genGrid.ipynb rename docs/{getting_started.ipynb => examples/test_load_dem.ipynb} (50%) diff --git a/docs/examples/example_magic_funcs.ipynb b/docs/examples/example_magic_funcs.ipynb new file mode 100644 index 0000000..8045d3f --- /dev/null +++ b/docs/examples/example_magic_funcs.ipynb @@ -0,0 +1,157 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## example magic functions" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import topotoolbox as topo\n", + "import matplotlib.pyplot as plt\n", + "import numpy as np" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Iterating through dem:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "dem = topo.GridObject.gen_random_bool(rows=4, columns=4)\n", + "for i in dem:\n", + " print(i)\n", + "\n", + "print(dem[2][2])\n", + "dem[2][2] = 2\n", + "print(dem[2][2])" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Comparing dems:\n", + "- `>`, `<`, `>=`, `<=`\n", + "- and: `&`\n", + "- or: `|`\n", + "- xor: `^`\n", + "\n", + "(in the binary plots, black = true)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "dem1 = topo.GridObject.gen_random(rows=32, columns=32, hillsize=24)\n", + "dem2 = topo.GridObject.gen_random(rows=32, columns=32, hillsize=32)\n", + "\n", + "fig, (ax1, ax2, ax3, ax4, ax5, ax6) = plt.subplots(1, 6, figsize=(14,4))\n", + "im1 = ax1.imshow(dem1, cmap='terrain')\n", + "ax1.set_title('dem1')\n", + "im2 = ax2.imshow(dem2, cmap='terrain')\n", + "ax2.set_title('dem2')\n", + "\n", + "im3 = ax3.imshow((dem1 > dem2), cmap='binary')\n", + "ax3.set_title('>')\n", + "im4 = ax4.imshow((dem1 < dem2), cmap='binary')\n", + "ax4.set_title('<')\n", + "im5 = ax5.imshow((dem1 >= dem2), cmap='binary')\n", + "ax5.set_title('>=')\n", + "im6 = ax6.imshow((dem1 <= dem2), cmap='binary')\n", + "ax6.set_title('<=')\n", + "\n", + "plt.show()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "dem1 = topo.GridObject.gen_random_bool()\n", + "dem2 = topo.GridObject.gen_random_bool()\n", + "\n", + "fig, (ax1, ax2, ax3, ax4, ax5) = plt.subplots(1, 5, figsize=(12,4))\n", + "im1 = ax1.imshow(dem1, cmap='binary')\n", + "ax1.set_title('dem1')\n", + "im2 = ax2.imshow(dem2, cmap='binary')\n", + "ax2.set_title('dem2')\n", + "\n", + "im3 = ax3.imshow((dem1 & dem2), cmap='binary')\n", + "ax3.set_title('and')\n", + "im4 = ax4.imshow((dem1 | dem2), cmap='binary')\n", + "ax4.set_title('or')\n", + "im5 = ax5.imshow((dem1 ^ dem2), cmap='binary')\n", + "ax5.set_title('xor')\n", + "\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Adding two dems and adding a int to all cells of a dem: (works the same way when using `-`, `*` or `/`)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "dem1 = topo.GridObject.gen_random(rows=32, columns=32, hillsize=32)\n", + "dem2 = topo.GridObject.gen_random(rows=32, columns=32, hillsize=16)\n", + "\n", + "fig, (ax1, ax2, ax3) = plt.subplots(1, 3)\n", + "ax1.imshow(dem1, cmap='terrain')\n", + "ax2.imshow(dem2, cmap='terrain')\n", + "\n", + "ax3.imshow((dem1 + dem2), cmap='terrain')\n", + "plt.show()\n", + "\n", + "print('dem3:\\n', dem1)\n", + "print('dem3 + 100:\\n', dem1 + 100)\n" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.12" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/examples/test_GridObject.ipynb b/docs/examples/test_GridObject.ipynb new file mode 100644 index 0000000..4b224c1 --- /dev/null +++ b/docs/examples/test_GridObject.ipynb @@ -0,0 +1,89 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## test GridObject" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import topotoolbox as topo\n", + "\n", + "import matplotlib.pyplot as plt" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "dem = topo.GridObject.gen_random()\n", + "dem.info()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "filled = dem.fillsinks()\n", + "\n", + "flats, sills = filled.identifyflats()\n", + "\n", + "# plotting:\n", + "fig, (ax1, ax2, ax3) = plt.subplots(1, 3, figsize=(12,4))\n", + "ax1.imshow(dem, cmap='terrain')\n", + "ax1.set_title('dem')\n", + "ax2.imshow(filled, cmap='terrain')\n", + "ax2.set_title('filled')\n", + "\n", + "ax3.imshow(flats, cmap='Reds', alpha=0.5)\n", + "ax3.imshow(sills, cmap='Blues', alpha=0.5)\n", + "ax3.set_title('flats and sills')\n", + "\n", + "plt.show()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "raw = filled.identifyflats(raw=True)\n", + "\n", + "img = plt.imshow(raw, cmap='binary')\n", + "plt.show()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.12" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/examples/test_genGrid.ipynb b/docs/examples/test_genGrid.ipynb new file mode 100644 index 0000000..6b828f9 --- /dev/null +++ b/docs/examples/test_genGrid.ipynb @@ -0,0 +1,70 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## test_genGrid" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import topotoolbox as topo\n", + "import matplotlib.pyplot as plt\n", + "from matplotlib.colors import LightSource\n", + "\n", + "# generating Gridobject with random terrain\n", + "dem = topo.GridObject.gen_random()\n", + "\n", + "# plotting dem with hillshade\n", + "ls = LightSource(azdeg=270, altdeg=60)\n", + "hillshade = ls.hillshade(dem.z, vert_exag=1/dem.cellsize)\n", + "img = plt.imshow(dem.z, cmap='terrain')\n", + "img_overlay = plt.imshow(hillshade, cmap=\"gray\", alpha=0.25)\n", + "plt.colorbar(img)\n", + "plt.show()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "dem = dem.fillsinks()\n", + "\n", + "ls = LightSource(azdeg=270, altdeg=60)\n", + "hillshade = ls.hillshade(dem.z, vert_exag=1/dem.cellsize)\n", + "img = plt.imshow(dem.z, cmap='terrain')\n", + "img_overlay = plt.imshow(hillshade, cmap=\"gray\", alpha=0.25)\n", + "plt.colorbar(img)\n", + "plt.show()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.12" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/getting_started.ipynb b/docs/examples/test_load_dem.ipynb similarity index 50% rename from docs/getting_started.ipynb rename to docs/examples/test_load_dem.ipynb index 539126a..47705b1 100644 --- a/docs/getting_started.ipynb +++ b/docs/examples/test_load_dem.ipynb @@ -4,16 +4,43 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Getting Started with TopoToolbox" + "## test load dem" ] }, { "cell_type": "code", - "execution_count": 1, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ - "import topotoolbox" + "import topotoolbox as topo" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "print(topo.get_dem_names())" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "dem = topo.load_dem(\"taiwan\")\n", + "dem.info()\n", + "print(topo.get_cache_contents())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Run topo.clear_cache() do remove all files in the TopoToolbox cache." ] } ], 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." ] } ], From 5e9fecf0bd95b0af4c304dd21e9ee7b7a78cf941 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 10 Jun 2024 19:24:33 +0200 Subject: [PATCH 07/24] modify layout --- README.md | 11 ----------- docs/README.md | 10 ++++++++++ docs/example_list.rst | 29 +++++++++++++++++++++++++++++ docs/examples.rst | 4 ---- docs/index.rst | 9 +++++---- docs/tutorial.rst | 18 ++++++++++++++++++ 6 files changed, 62 insertions(+), 19 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/example_list.rst delete mode 100644 docs/examples.rst create mode 100644 docs/tutorial.rst diff --git a/README.md b/README.md index ea0ceeb..8c884e1 100644 --- a/README.md +++ b/README.md @@ -75,14 +75,3 @@ For any operating system, install the following: ### Mac [work in progress] - -## Generation Sphinx Documentation - -To generate the Sphinx documentation HTML page, run the following commands: - -```bash -cd /path/to/topotoolbox/docs/ -make html -``` - -then open the `pytopotoolbox/docs/_build/html/index.html` file in your browser. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..0761ceb --- /dev/null +++ b/docs/README.md @@ -0,0 +1,10 @@ +# Generation Sphinx Documentation + +To generate the Sphinx documentation HTML page, run the following commands: + +```bash +cd /path/to/topotoolbox/docs/ +make html +``` + +then open the `pytopotoolbox/docs/_build/html/index.html` file in your browser. diff --git a/docs/example_list.rst b/docs/example_list.rst new file mode 100644 index 0000000..b8e23e5 --- /dev/null +++ b/docs/example_list.rst @@ -0,0 +1,29 @@ +Examples +======== + +In this section there examples you can use to gain a better understanding of the TopoToolbox and how to use it with python. + +Displaying DEM's +---------------- + +.. toctree:: + :maxdepth: 1 + + examples/test_genGrid + +Loading examples +---------------- + +.. toctree:: + :maxdepth: 1 + + examples/test_load_dem + +Generating Grid Objects from .tif files +--------------------------------------- + +.. toctree:: + :maxdepth: 1 + + examples/test_GridObject + diff --git a/docs/examples.rst b/docs/examples.rst deleted file mode 100644 index 2940650..0000000 --- a/docs/examples.rst +++ /dev/null @@ -1,4 +0,0 @@ -Examples -======== - -Here we can link to the example .ipynb files later on. diff --git a/docs/index.rst b/docs/index.rst index 6b0caf7..5935e34 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,10 +5,11 @@ Welcome to TopoToolbox's python documentation! :maxdepth: 1 :caption: Contents: - api - installing - getting_started - examples + Installing + Tutorial + Examples + API + Indices and tables 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 +----------------------- + From e60dd4ea682cdce3df173d305b4f8551d182b923 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 10 Jun 2024 19:24:45 +0200 Subject: [PATCH 08/24] build on push --- .github/workflows/docs.yaml | 41 +++++++++++++++++++++++++++++++++++++ docs/conf.py | 2 ++ docs/requirements.txt | 3 +++ 3 files changed, 46 insertions(+) create mode 100644 .github/workflows/docs.yaml create mode 100644 docs/requirements.txt diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..8f11b0c --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,41 @@ +name: docs + +on: + push: + branches: ["main"] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install Python build dependencies + run: | + python -m pip install --upgrade pip + pip install -r ${{ github.workspace }}/docs/requirements.txt + + - name: Build Sphinx documentation + working-directory: ${{ github.workspace }}/docs + run: 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/docs/conf.py b/docs/conf.py index a4e088f..61c9c01 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -8,7 +8,9 @@ import os import sys + import sphinx_book_theme +import topotoolbox sys.path.insert(0, os.path.abspath('../src/topotoolbox')) diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..3e75f64 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +Sphinx==7.3.7 +sphinx-book-theme==1.1.2 +nbsphinx==0.9.4 From 24ca13744fad3e728f74d9b028f15d415cdf5b98 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 10 Jun 2024 19:26:12 +0200 Subject: [PATCH 09/24] modify yaml to build on docs branch --- .github/workflows/docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 8f11b0c..15c3eb3 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -2,7 +2,7 @@ name: docs on: push: - branches: ["main"] + branches: ["docs"] jobs: build: From 1f6209176cba0275547091419c54af630ace7dfc Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 10 Jun 2024 19:30:42 +0200 Subject: [PATCH 10/24] removed topotoolbox import The ipynb will not be build since the topotoolbox import is missing --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 61c9c01..61c6376 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,7 +10,7 @@ import sys import sphinx_book_theme -import topotoolbox +# import topotoolbox sys.path.insert(0, os.path.abspath('../src/topotoolbox')) From f293fd2b9841d58d2dea131960a5ffe9f43470ce Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 10 Jun 2024 19:34:31 +0200 Subject: [PATCH 11/24] added requirements --- docs/requirements.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/requirements.txt b/docs/requirements.txt index 3e75f64..258508e 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +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 From 745ca9f8d33cf460e52ab434abb85cb7792c4545 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 10 Jun 2024 19:36:29 +0200 Subject: [PATCH 12/24] modified conf.py --- docs/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 61c6376..e46312d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,3 +41,7 @@ html_theme = 'sphinx_book_theme' html_static_path = ['_static'] html_logo = 'logo.png' + +# -- Options for nbsphinx ---------------------------------------------------- + +nbsphinx_allow_errors = True From 9caaad377a61e1683166033d8f8b5890d48d3279 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 10 Jun 2024 19:42:01 +0200 Subject: [PATCH 13/24] added pandoc install --- .github/workflows/docs.yaml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 15c3eb3..624ea54 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -9,7 +9,10 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v4- + + name: Install Pandoc + run: sudo apt-get install -y pandoc - name: Install Python build dependencies run: | From 50f3a589b2f6de7e578e19108d783b866dbd8c90 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 10 Jun 2024 19:42:56 +0200 Subject: [PATCH 14/24] added '-' before name: pandoc --- .github/workflows/docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 624ea54..9eb254e 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -11,7 +11,7 @@ jobs: - name: Checkout uses: actions/checkout@v4- - name: Install Pandoc + - name: Install Pandoc run: sudo apt-get install -y pandoc - name: Install Python build dependencies From fb2f8187c5582820761d12831ad91b4084cb79c3 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 10 Jun 2024 19:48:08 +0200 Subject: [PATCH 15/24] fix version number --- .github/workflows/docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 9eb254e..09cf7af 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -9,7 +9,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v4- + uses: actions/checkout@v4 - name: Install Pandoc run: sudo apt-get install -y pandoc From 0931fb88df2f8896547dbcb550a91c466ac8b9c4 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 10 Jun 2024 22:10:13 +0200 Subject: [PATCH 16/24] change artifact path --- .github/workflows/docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 09cf7af..4856dba 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -26,7 +26,7 @@ jobs: - name: Package artifact uses: actions/upload-pages-artifact@v3 with: - path: ${{ github.workspace }}/docs/_build/html + path: ${{ github.workspace }}/docs/_build/html/index.html deploy: needs: build From 5c03e25a19cd4512b4b6d3d7ed0412ea6cc5cb37 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 10 Jun 2024 22:16:15 +0200 Subject: [PATCH 17/24] revert path --- .github/workflows/docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 4856dba..09cf7af 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -26,7 +26,7 @@ jobs: - name: Package artifact uses: actions/upload-pages-artifact@v3 with: - path: ${{ github.workspace }}/docs/_build/html/index.html + path: ${{ github.workspace }}/docs/_build/html deploy: needs: build From 9c1caa7f8752a9168a2293aec52e739c8d31fa4a Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Tue, 11 Jun 2024 12:02:03 +0200 Subject: [PATCH 18/24] add topotoolbox to build --- .github/workflows/docs.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 09cf7af..8335041 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -18,6 +18,7 @@ jobs: 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 From 3212843f5e20dbf5e0fd20fe77af78675dc3c7ca Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Tue, 11 Jun 2024 17:33:09 +0200 Subject: [PATCH 19/24] api docs with auto summary --- .github/workflows/docs.yaml | 4 ++- docs/_autosummary/topotoolbox.GridObject.rst | 28 ++++++++++++++++ docs/_autosummary/topotoolbox.utils.rst | 34 ++++++++++++++++++++ docs/api.rst | 24 +++----------- docs/conf.py | 22 +++++++++++-- 5 files changed, 89 insertions(+), 23 deletions(-) create mode 100644 docs/_autosummary/topotoolbox.GridObject.rst create mode 100644 docs/_autosummary/topotoolbox.utils.rst diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 8335041..95ceddb 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -22,7 +22,9 @@ jobs: - name: Build Sphinx documentation working-directory: ${{ github.workspace }}/docs - run: make html + run: | + make clean + make html - name: Package artifact uses: actions/upload-pages-artifact@v3 diff --git a/docs/_autosummary/topotoolbox.GridObject.rst b/docs/_autosummary/topotoolbox.GridObject.rst new file mode 100644 index 0000000..030c9ef --- /dev/null +++ b/docs/_autosummary/topotoolbox.GridObject.rst @@ -0,0 +1,28 @@ +topotoolbox.GridObject +====================== + +.. currentmodule:: topotoolbox + +.. autoclass:: GridObject + + + .. automethod:: __init__ + + + .. rubric:: Methods + + .. autosummary:: + + ~GridObject.__init__ + ~GridObject.fillsinks + ~GridObject.gen_empty + ~GridObject.gen_random + ~GridObject.gen_random_bool + ~GridObject.identifyflats + ~GridObject.info + + + + + + \ No newline at end of file diff --git a/docs/_autosummary/topotoolbox.utils.rst b/docs/_autosummary/topotoolbox.utils.rst new file mode 100644 index 0000000..c353e41 --- /dev/null +++ b/docs/_autosummary/topotoolbox.utils.rst @@ -0,0 +1,34 @@ +topotoolbox.utils +================= + +.. automodule:: topotoolbox.utils + + + + + + + + .. rubric:: Functions + + .. autosummary:: + + clear_cache + get_cache_contents + get_dem_names + get_save_location + load_dem + read_tif + + + + + + + + + + + + + diff --git a/docs/api.rst b/docs/api.rst index 6887991..3aa7ab0 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,24 +1,8 @@ API Documentation ================= -utils ------ +.. autosummary:: topotoolbox + :toctree: _autosummary -.. automodule:: topotoolbox.utils - :members: - :undoc-members: - :show-inheritance: - - -grid_object ------------ - -.. automodule:: topotoolbox.grid_object - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: topotoolbox.gridmixins - :members: - :undoc-members: - :show-inheritance: + topotoolbox.GridObject + topotoolbox.utils diff --git a/docs/conf.py b/docs/conf.py index e46312d..c373ca9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,16 +10,18 @@ import sys import sphinx_book_theme -# import topotoolbox +import topotoolbox -sys.path.insert(0, os.path.abspath('../src/topotoolbox')) + +# sys.path.insert(0, os.path.abspath('../src/topotoolbox')) extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode', 'sphinx.ext.todo', + 'sphinx.ext.autosummary', 'nbsphinx', ] @@ -42,6 +44,22 @@ html_static_path = ['_static'] html_logo = 'logo.png' +html_context = { + "default_mode": "light", +} + # -- Options for nbsphinx ---------------------------------------------------- nbsphinx_allow_errors = True + +# -- Options for autodoc ----------------------------------------------------- + +# autodoc_class_members_toctree = False +autodoc_default_options = { + 'members': True, + 'undoc-members': True, + 'private-members': False, + 'special-members': '__init__', + 'inherited-members': True, + 'show-inheritance': True, +} From e4c779a49dd6f14cbc67ea8b32fc3bdbc05dc7f1 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Tue, 11 Jun 2024 18:52:34 +0200 Subject: [PATCH 20/24] remove examples from docs/ --- docs/Makefile | 8 ++ docs/README.md | 1 + docs/example_list.rst | 6 +- docs/examples/example_magic_funcs.ipynb | 157 ------------------------ docs/examples/test_GridObject.ipynb | 89 -------------- docs/examples/test_genGrid.ipynb | 70 ----------- docs/examples/test_load_dem.ipynb | 68 ---------- 7 files changed, 12 insertions(+), 387 deletions(-) delete mode 100644 docs/examples/example_magic_funcs.ipynb delete mode 100644 docs/examples/test_GridObject.ipynb delete mode 100644 docs/examples/test_genGrid.ipynb delete mode 100644 docs/examples/test_load_dem.ipynb diff --git a/docs/Makefile b/docs/Makefile index d4bb2cb..fd4841d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -7,6 +7,8 @@ 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: @@ -17,4 +19,10 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile + @echo "Copying examples directory..." + @cp -r $(EXAMPLEDIR) $(DOCEXAMPLEDIR) + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + @echo "Cleaning up examples directory..." + @rm -rf $(DOCEXAMPLEDIR) diff --git a/docs/README.md b/docs/README.md index 0761ceb..ee06885 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,7 @@ To generate the Sphinx documentation HTML page, run the following commands: ```bash cd /path/to/topotoolbox/docs/ +make clean make html ``` diff --git a/docs/example_list.rst b/docs/example_list.rst index b8e23e5..d564d89 100644 --- a/docs/example_list.rst +++ b/docs/example_list.rst @@ -9,7 +9,7 @@ Displaying DEM's .. toctree:: :maxdepth: 1 - examples/test_genGrid + /_examples/test_genGrid Loading examples ---------------- @@ -17,7 +17,7 @@ Loading examples .. toctree:: :maxdepth: 1 - examples/test_load_dem + /_examples/test_load_dem Generating Grid Objects from .tif files --------------------------------------- @@ -25,5 +25,5 @@ Generating Grid Objects from .tif files .. toctree:: :maxdepth: 1 - examples/test_GridObject + /_examples/test_GridObject diff --git a/docs/examples/example_magic_funcs.ipynb b/docs/examples/example_magic_funcs.ipynb deleted file mode 100644 index 8045d3f..0000000 --- a/docs/examples/example_magic_funcs.ipynb +++ /dev/null @@ -1,157 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## example magic functions" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import topotoolbox as topo\n", - "import matplotlib.pyplot as plt\n", - "import numpy as np" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Iterating through dem:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "dem = topo.GridObject.gen_random_bool(rows=4, columns=4)\n", - "for i in dem:\n", - " print(i)\n", - "\n", - "print(dem[2][2])\n", - "dem[2][2] = 2\n", - "print(dem[2][2])" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Comparing dems:\n", - "- `>`, `<`, `>=`, `<=`\n", - "- and: `&`\n", - "- or: `|`\n", - "- xor: `^`\n", - "\n", - "(in the binary plots, black = true)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "dem1 = topo.GridObject.gen_random(rows=32, columns=32, hillsize=24)\n", - "dem2 = topo.GridObject.gen_random(rows=32, columns=32, hillsize=32)\n", - "\n", - "fig, (ax1, ax2, ax3, ax4, ax5, ax6) = plt.subplots(1, 6, figsize=(14,4))\n", - "im1 = ax1.imshow(dem1, cmap='terrain')\n", - "ax1.set_title('dem1')\n", - "im2 = ax2.imshow(dem2, cmap='terrain')\n", - "ax2.set_title('dem2')\n", - "\n", - "im3 = ax3.imshow((dem1 > dem2), cmap='binary')\n", - "ax3.set_title('>')\n", - "im4 = ax4.imshow((dem1 < dem2), cmap='binary')\n", - "ax4.set_title('<')\n", - "im5 = ax5.imshow((dem1 >= dem2), cmap='binary')\n", - "ax5.set_title('>=')\n", - "im6 = ax6.imshow((dem1 <= dem2), cmap='binary')\n", - "ax6.set_title('<=')\n", - "\n", - "plt.show()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "dem1 = topo.GridObject.gen_random_bool()\n", - "dem2 = topo.GridObject.gen_random_bool()\n", - "\n", - "fig, (ax1, ax2, ax3, ax4, ax5) = plt.subplots(1, 5, figsize=(12,4))\n", - "im1 = ax1.imshow(dem1, cmap='binary')\n", - "ax1.set_title('dem1')\n", - "im2 = ax2.imshow(dem2, cmap='binary')\n", - "ax2.set_title('dem2')\n", - "\n", - "im3 = ax3.imshow((dem1 & dem2), cmap='binary')\n", - "ax3.set_title('and')\n", - "im4 = ax4.imshow((dem1 | dem2), cmap='binary')\n", - "ax4.set_title('or')\n", - "im5 = ax5.imshow((dem1 ^ dem2), cmap='binary')\n", - "ax5.set_title('xor')\n", - "\n", - "plt.show()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Adding two dems and adding a int to all cells of a dem: (works the same way when using `-`, `*` or `/`)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "dem1 = topo.GridObject.gen_random(rows=32, columns=32, hillsize=32)\n", - "dem2 = topo.GridObject.gen_random(rows=32, columns=32, hillsize=16)\n", - "\n", - "fig, (ax1, ax2, ax3) = plt.subplots(1, 3)\n", - "ax1.imshow(dem1, cmap='terrain')\n", - "ax2.imshow(dem2, cmap='terrain')\n", - "\n", - "ax3.imshow((dem1 + dem2), cmap='terrain')\n", - "plt.show()\n", - "\n", - "print('dem3:\\n', dem1)\n", - "print('dem3 + 100:\\n', dem1 + 100)\n" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.12" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/docs/examples/test_GridObject.ipynb b/docs/examples/test_GridObject.ipynb deleted file mode 100644 index 4b224c1..0000000 --- a/docs/examples/test_GridObject.ipynb +++ /dev/null @@ -1,89 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## test GridObject" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import topotoolbox as topo\n", - "\n", - "import matplotlib.pyplot as plt" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "dem = topo.GridObject.gen_random()\n", - "dem.info()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "filled = dem.fillsinks()\n", - "\n", - "flats, sills = filled.identifyflats()\n", - "\n", - "# plotting:\n", - "fig, (ax1, ax2, ax3) = plt.subplots(1, 3, figsize=(12,4))\n", - "ax1.imshow(dem, cmap='terrain')\n", - "ax1.set_title('dem')\n", - "ax2.imshow(filled, cmap='terrain')\n", - "ax2.set_title('filled')\n", - "\n", - "ax3.imshow(flats, cmap='Reds', alpha=0.5)\n", - "ax3.imshow(sills, cmap='Blues', alpha=0.5)\n", - "ax3.set_title('flats and sills')\n", - "\n", - "plt.show()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "raw = filled.identifyflats(raw=True)\n", - "\n", - "img = plt.imshow(raw, cmap='binary')\n", - "plt.show()" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.12" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/docs/examples/test_genGrid.ipynb b/docs/examples/test_genGrid.ipynb deleted file mode 100644 index 6b828f9..0000000 --- a/docs/examples/test_genGrid.ipynb +++ /dev/null @@ -1,70 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## test_genGrid" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import topotoolbox as topo\n", - "import matplotlib.pyplot as plt\n", - "from matplotlib.colors import LightSource\n", - "\n", - "# generating Gridobject with random terrain\n", - "dem = topo.GridObject.gen_random()\n", - "\n", - "# plotting dem with hillshade\n", - "ls = LightSource(azdeg=270, altdeg=60)\n", - "hillshade = ls.hillshade(dem.z, vert_exag=1/dem.cellsize)\n", - "img = plt.imshow(dem.z, cmap='terrain')\n", - "img_overlay = plt.imshow(hillshade, cmap=\"gray\", alpha=0.25)\n", - "plt.colorbar(img)\n", - "plt.show()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "dem = dem.fillsinks()\n", - "\n", - "ls = LightSource(azdeg=270, altdeg=60)\n", - "hillshade = ls.hillshade(dem.z, vert_exag=1/dem.cellsize)\n", - "img = plt.imshow(dem.z, cmap='terrain')\n", - "img_overlay = plt.imshow(hillshade, cmap=\"gray\", alpha=0.25)\n", - "plt.colorbar(img)\n", - "plt.show()" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.12" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/docs/examples/test_load_dem.ipynb b/docs/examples/test_load_dem.ipynb deleted file mode 100644 index 47705b1..0000000 --- a/docs/examples/test_load_dem.ipynb +++ /dev/null @@ -1,68 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## test load dem" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import topotoolbox as topo" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "print(topo.get_dem_names())" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "dem = topo.load_dem(\"taiwan\")\n", - "dem.info()\n", - "print(topo.get_cache_contents())" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Run topo.clear_cache() do remove all files in the TopoToolbox cache." - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.12" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} From 1ca5e92489f0c67ed1dd9a01c586bd2eda4c1369 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Fri, 14 Jun 2024 11:57:15 +0200 Subject: [PATCH 21/24] Add autosummary and nbgallery --- .gitignore | 11 +++---- docs/Makefile | 17 ++++++---- docs/README.md | 2 +- docs/_autosummary/topotoolbox.GridObject.rst | 28 ---------------- docs/_autosummary/topotoolbox.utils.rst | 34 -------------------- docs/api.rst | 6 ++-- docs/conf.py | 7 ++-- docs/example_list.rst | 29 ----------------- docs/examples.rst | 8 +++++ docs/index.rst | 2 +- 10 files changed, 30 insertions(+), 114 deletions(-) delete mode 100644 docs/_autosummary/topotoolbox.GridObject.rst delete mode 100644 docs/_autosummary/topotoolbox.utils.rst delete mode 100644 docs/example_list.rst create mode 100644 docs/examples.rst diff --git a/.gitignore b/.gitignore index e353646..c7faf32 100644 --- a/.gitignore +++ b/.gitignore @@ -1,17 +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__ # ignore build docs -docs/_build/* \ No newline at end of file +docs/_build/* + +# ignore _autosummary +docs/_autosummary/* \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index fd4841d..285325e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -7,22 +7,25 @@ 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 -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile +# Target to build HTML documentation, including copying/removing examples +html: @echo "Copying examples directory..." @cp -r $(EXAMPLEDIR) $(DOCEXAMPLEDIR) - - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - + @$(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 index ee06885..bff9c1d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # Generation Sphinx Documentation -To generate the Sphinx documentation HTML page, run the following commands: +To generate the Sphinx documentation HTML page, run the following commands (Linux): ```bash cd /path/to/topotoolbox/docs/ diff --git a/docs/_autosummary/topotoolbox.GridObject.rst b/docs/_autosummary/topotoolbox.GridObject.rst deleted file mode 100644 index 030c9ef..0000000 --- a/docs/_autosummary/topotoolbox.GridObject.rst +++ /dev/null @@ -1,28 +0,0 @@ -topotoolbox.GridObject -====================== - -.. currentmodule:: topotoolbox - -.. autoclass:: GridObject - - - .. automethod:: __init__ - - - .. rubric:: Methods - - .. autosummary:: - - ~GridObject.__init__ - ~GridObject.fillsinks - ~GridObject.gen_empty - ~GridObject.gen_random - ~GridObject.gen_random_bool - ~GridObject.identifyflats - ~GridObject.info - - - - - - \ No newline at end of file diff --git a/docs/_autosummary/topotoolbox.utils.rst b/docs/_autosummary/topotoolbox.utils.rst deleted file mode 100644 index c353e41..0000000 --- a/docs/_autosummary/topotoolbox.utils.rst +++ /dev/null @@ -1,34 +0,0 @@ -topotoolbox.utils -================= - -.. automodule:: topotoolbox.utils - - - - - - - - .. rubric:: Functions - - .. autosummary:: - - clear_cache - get_cache_contents - get_dem_names - get_save_location - load_dem - read_tif - - - - - - - - - - - - - diff --git a/docs/api.rst b/docs/api.rst index 3aa7ab0..05f9cd2 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,8 +1,8 @@ API Documentation ================= -.. autosummary:: topotoolbox +.. autosummary:: :toctree: _autosummary + :recursive: - topotoolbox.GridObject - topotoolbox.utils + topotoolbox \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index c373ca9..53c357b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,14 +14,12 @@ import topotoolbox -# sys.path.insert(0, os.path.abspath('../src/topotoolbox')) - extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode', 'sphinx.ext.todo', - 'sphinx.ext.autosummary', 'nbsphinx', ] @@ -54,7 +52,6 @@ # -- Options for autodoc ----------------------------------------------------- -# autodoc_class_members_toctree = False autodoc_default_options = { 'members': True, 'undoc-members': True, @@ -63,3 +60,5 @@ 'inherited-members': True, 'show-inheritance': True, } + +autosummary_generate = True # Enable autosummary to generate stub files diff --git a/docs/example_list.rst b/docs/example_list.rst deleted file mode 100644 index d564d89..0000000 --- a/docs/example_list.rst +++ /dev/null @@ -1,29 +0,0 @@ -Examples -======== - -In this section there examples you can use to gain a better understanding of the TopoToolbox and how to use it with python. - -Displaying DEM's ----------------- - -.. toctree:: - :maxdepth: 1 - - /_examples/test_genGrid - -Loading examples ----------------- - -.. toctree:: - :maxdepth: 1 - - /_examples/test_load_dem - -Generating Grid Objects from .tif files ---------------------------------------- - -.. toctree:: - :maxdepth: 1 - - /_examples/test_GridObject - 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 index 5935e34..c90419e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,7 +7,7 @@ Welcome to TopoToolbox's python documentation! Installing Tutorial - Examples + Examples API From 3fe5db3e993ed287d72229c3f8d9d74bfc5d081e Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 17 Jun 2024 13:32:44 +0200 Subject: [PATCH 22/24] Set branch to main --- .github/workflows/docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 95ceddb..1591b9b 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -2,7 +2,7 @@ name: docs on: push: - branches: ["docs"] + branches: ["main"] jobs: build: From e88bc13fd9d5a13337d1f74ed8fc2091b927ba87 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 17 Jun 2024 14:03:10 +0200 Subject: [PATCH 23/24] removed pyPi reference --- docs/installing.rst | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/installing.rst b/docs/installing.rst index ee2c588..96f6c49 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -1,13 +1,6 @@ How to install ============== -Installing topotoolbox with pip -------------------------------- - -[not working jet!] :: - - $ pip install topotoolbox - Generating/Installing distribution archives ------------------------------------------- From e137c4d010b2064bf2830f3f4f9ea1dd89a85f46 Mon Sep 17 00:00:00 2001 From: Teschl <69400012+Teschl@users.noreply.github.com> Date: Mon, 17 Jun 2024 14:04:20 +0200 Subject: [PATCH 24/24] Added dependencies guide --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index bff9c1d..fed538e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # Generation Sphinx Documentation -To generate the Sphinx documentation HTML page, run the following commands (Linux): +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/