From 0f9c810b203ff88a7b25eab746dc3ff9605c8905 Mon Sep 17 00:00:00 2001 From: Theo <69400012+Teschl@users.noreply.github.com> Date: Wed, 26 Jun 2024 10:28:14 +0200 Subject: [PATCH] Update Documentation and add CONTRIBUTING (#40) * Add introduction and first badges * Add CONTRIBUTING.md * Add badges and introduction * Add Contributing to docs * Rephrase License reference * Change tutorial to Jupyter Notebook * Streamline docs build process * Fix structure and grammar * Add notebook tutorial --- .gitignore | 5 +- CONTRIBUTING.md | 53 +++++++++++++++++++++ README.md | 31 +++++++++++- docs/Makefile | 14 +++--- docs/README.md | 2 +- docs/conf.py | 3 +- docs/examples.rst | 8 ++-- docs/index.rst | 37 ++++++++++++--- docs/requirements.txt | 2 +- docs/tutorial.ipynb | 106 ++++++++++++++++++++++++++++++++++++++++++ docs/tutorial.rst | 18 ------- 11 files changed, 240 insertions(+), 39 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/tutorial.ipynb delete mode 100644 docs/tutorial.rst diff --git a/.gitignore b/.gitignore index c7faf32..56c34b2 100644 --- a/.gitignore +++ b/.gitignore @@ -11,4 +11,7 @@ tests/__pycache__ docs/_build/* # ignore _autosummary -docs/_autosummary/* \ No newline at end of file +docs/_autosummary/* + +# ignore _temp +docs/_temp \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1863079 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,53 @@ +# Contribution Guidelines + +First off, thanks for taking the time to contribute! + +The following is a set of guidelines for contributing to the TopoToolbox Python Library. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. + +## How Can I Contribute? + +### Reporting Bugs + +If you find a bug, please report it by opening an issue. Please include: + +- A clear and descriptive title. +- A detailed description of the problem. +- Steps to reproduce the issue. +- Any error messages you encountered. + +### Suggesting Enhancements + +If you have an idea for an enhancement or new feature, please open an issue to discuss it. Please include: + +- A clear and descriptive title. +- A detailed description of the proposed enhancement. +- Any relevant examples or screenshots. + +### Submitting Pull Requests + +If you have a patch or new feature that you would like to contribute, please submit a [pull request (PR)](https://guides.github.com/introduction/flow/). Before you do, please ensure the following: + +1. Fork the repository and create your branch from `main`. +2. If you have added code that should be tested, add tests. +3. If you have changed APIs, update the documentation. +4. Ensure the test suite passes. +5. Make sure your code lints. + +### Code Style + +Please follow the [PEP 8](https://pep8.org/) style guide for Python code. + +### Commit Messages + +Use [clear and descriptive commit messages](https://cbea.ms/git-commit/). Follow these conventions: + +- Use the present tense ("Analyze terrain" not "Analyzed terrain"). +- Use the imperative mood ("Generate contour map" not "Generates contour map"). +- Limit the first line to 50 characters or less. All other lines should not be longer than 72 characters. +- Reference issues and pull requests liberally. + +### Documentation + +Improvements to the documentation are always welcome. Please ensure that your changes are clear and concise. + +Thank you for contributing! diff --git a/README.md b/README.md index 8c884e1..8c9dd45 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,27 @@ +

+ pytopotoolbox Logo +

+ +------------------- + +![GitHub Release](https://img.shields.io/github/v/release/topotoolbox/pytopotoolbox) +![PyPI - Version](https://img.shields.io/pypi/v/topotoolbox) +[![Tests](https://github.com/topotoolbox/pytopotoolbox/workflows/CI/badge.svg)](https://github.com/topotoolbox/pytopotoolbox/actions) +![GitHub License](https://img.shields.io/github/license/topotoolbox/pytopotoolbox) + # pytopotoolbox -Python interface to TopoToolbox. +**TopoToolbox** is a Python library that provides a set of functions and classes that support the analysis of relief and flow pathways in digital elevation models (DEMs). The major aim of TopoToolbox is to offer helpful analytical GIS utilities in a non-GIS environment in order to support the simultaneous application of GIS-specific and other quantitative methods. + +The documentation is located at [https://topotoolbox.github.io/pytopotoolbox/](https://topotoolbox.github.io/pytopotoolbox/). + +This python library is based on the [TopoToolbox](https://topotoolbox.wordpress.com/) for Matlab and uses the API provided by [libtopotoolbox](https://topotoolbox.github.io/libtopotoolbox/) to compute efficiently. + +## Getting started + +To get started head to [pytopotoolbox/tutorial](https://topotoolbox.github.io/pytopotoolbox/tutorial.html). If you need more examples see [pytopotoolbox/examples](https://topotoolbox.github.io/pytopotoolbox/examples.html) or reference the API documentation [pytopotoolbox/api](https://topotoolbox.github.io/pytopotoolbox/api.html). + +The example files are also available as Jupyter Notebook files in the [./examples](/examples/) folder. Feel free to download and play around with them to gain a better understanding of the functionality of the TopoToolbox. ## Generating/Installing distribution archives @@ -75,3 +96,11 @@ For any operating system, install the following: ### Mac [work in progress] + +## Contributing + +If you would like to contribute to pytopotoolbox, check out the [Contribution Guidelines](./CONTRIBUTING.md). + +## License + +This project is licensed under the GPL-3.0 (GNU) License - see the [LICENSE](./LICENSE) file for details. diff --git a/docs/Makefile b/docs/Makefile index fbf9711..05540a3 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -9,7 +9,7 @@ SOURCEDIR = . BUILDDIR = _build EXAMPLEDIR = ../examples -DOCEXAMPLEDIR = _examples +TEMPDIR = _temp AUTOSUMMARYDIR = _autosummary # Put it first so that "make" without argument is like "make help". @@ -21,10 +21,12 @@ help: # Target to build HTML documentation, including copying/removing examples html: @echo "Copying examples directory..." - @cp -r $(EXAMPLEDIR) $(DOCEXAMPLEDIR) + @cp -r $(EXAMPLEDIR) $(TEMPDIR) + @echo "Copying CONTRIBUTING.md file..." + @cp -r ../CONTRIBUTING.md $(TEMPDIR)/CONTRIBUTING.md @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - @echo "Cleaning up _examples directory..." - @rm -rf $(DOCEXAMPLEDIR)/* + @echo "Removing _temp directory..." + @rm -rf $(TEMPDIR) @echo "Cleaning up _autosummary directory..." @rm -rf $(AUTOSUMMARYDIR)/* @@ -33,8 +35,8 @@ clean: @rm -rf $(BUILDDIR)/* @echo "Cleaning up '_autosummary' directory..." @rm -rf $(AUTOSUMMARYDIR)/* - @echo "Cleaning up '_examples' directory..." - @rm -rf $(DOCEXAMPLEDIR)/* + @echo "Removing '_temp' directory..." + @rm -rf $(TEMPDIR) # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/docs/README.md b/docs/README.md index fed538e..770ad84 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # 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): +Before being able to generate the Docs, make sure to install all the python dependencies: `pip install -r requirements.txt` and pandoc. To generate the Sphinx documentation HTML page, run the following commands (Linux): ```bash cd /path/to/topotoolbox/docs/ diff --git a/docs/conf.py b/docs/conf.py index 53c357b..681a410 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,6 +21,7 @@ 'sphinx.ext.viewcode', 'sphinx.ext.todo', 'nbsphinx', + 'myst_parser', ] project = 'TopoToolbox' @@ -32,7 +33,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration templates_path = ['_templates'] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md'] # -- Options for HTML output ------------------------------------------------- diff --git a/docs/examples.rst b/docs/examples.rst index 4b53a1b..de9e9f5 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -2,7 +2,7 @@ Examples ======== .. nbgallery:: - /_examples/test_genGrid - /_examples/test_GridObject - /_examples/test_load_dem - /_examples/example_magic_funcs + /_temp/test_genGrid + /_temp/test_GridObject + /_temp/test_load_dem + /_temp/example_magic_funcs diff --git a/docs/index.rst b/docs/index.rst index c90419e..8dac27c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,19 +1,44 @@ -Welcome to TopoToolbox's python documentation! +Welcome to TopoToolbox's Python Documentation! ============================================== +**TopoToolbox** is a Python library that provides a set of functions and classes that support the analysis of relief and flow pathways in digital elevation models (DEMs). The major aim of TopoToolbox is to offer helpful analytical GIS utilities in a non-GIS environment to support the simultaneous application of GIS-specific and other quantitative methods. + +This Python library is based on the `TopoToolbox `_ for Matlab and uses the API provided by `libtopotoolbox `_ to compute efficiently. + +Installing and Getting Started +------------------------------ + +If you want to learn how to install or build the TopoToolbox package, head over to the :doc:`installing ` page. + +If you have no experience with Python or this tool, the :doc:`tutorial ` might be a good place to start. There you will find a basic walkthrough of the functionality. + +Examples +-------- + +If you are familiar with the basic workflow of this package but want more examples to gain a better understanding of the different functions, the section :doc:`examples ` contains them in the form of Jupyter Notebooks. If you want to play around with them yourself, download them from the `GitHub repository `_. + +API Documentation +----------------- + +For further documentation regarding the functionality of this package, check out the :doc:`API documentation`. + +Contributing +------------ + +If you would like to contribute to pytopotoolbox, refer to the :doc:`_temp/CONTRIBUTING`. + .. toctree:: :maxdepth: 1 - :caption: Contents: + :hidden: Installing Tutorial Examples API + Contributing <_temp/CONTRIBUTING> - - -Indices and tables -================== +Indices and Tables +------------------ * :ref:`genindex` * :ref:`modindex` diff --git a/docs/requirements.txt b/docs/requirements.txt index 258508e..e5f557f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,4 +2,4 @@ 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 +myst_parser \ No newline at end of file diff --git a/docs/tutorial.ipynb b/docs/tutorial.ipynb new file mode 100644 index 0000000..32fffbf --- /dev/null +++ b/docs/tutorial.ipynb @@ -0,0 +1,106 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Tutorial\n", + "\n", + "This tutorial will guide you through the first steps of getting started with the topotoolbox for python. For further examples regarding the functionality and use cases of different functions/classes refer to the provided examples.\n", + "\n", + "## Installation\n", + "\n", + "Before you can use this tutorial the make sure to have the topotoolbox installed as per the installation guide.\n", + "\n", + "## Working with this file\n", + "\n", + "Feel free to [download this notebook](https://github.com/TopoToolbox/pytopotoolbox/blob/main/docs/tutorial.ipynb) so can follow these first steps in an interactive way.\n", + "\n", + "- Downloading the notebook: ```curl -o tutorial.ipynb https://raw.githubusercontent.com/topotoolbox/pytopotoolbox/main/docs/tutorial.ipynb``` or ```wget -O tutorial.ipynb https://raw.githubusercontent.com/topotoolbox/pytopotoolbox/main/docs/tutorial.ipynb```\n", + "\n", + "- You’ll need to install Jupyter Notebook to run this file: pip install notebook\n", + "\n", + "- To plot the DEMs you’ll also need matplotlib installed: pip install matplotlib\n", + "\n", + "- To run the notebook: jupyter notebook\n", + "\n", + "## Working on a first DEM\n", + "\n", + "Before you can actually use the topotoolbox package, it has to be imported. Since we want to plot the DEMs we will also import `matplotlib.pyplot`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import topotoolbox as topo\n", + "import matplotlib.pyplot as plt" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To automatically download one of the example files, the function `load_dem()` is used. To find out which files are available, use `get_dem_names()`. After the DEM has been created, you can view it’s attributes by using `GridObject.info()`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "print(topo.get_dem_names())\n", + "\n", + "dem = topo.load_dem('taiwan')\n", + "\n", + "print('\\nAttributes of the dem:')\n", + "dem.info()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "When plotting with matplotlib, the DEM behaves like a `np.ndarray`. So you’ll just have to pass it as an argument.\n", + "\n", + "If you want to increase the resolution of the plot, increase the `dpi` value" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fig, ax = plt.subplots(figsize=(10, 10), dpi=100)\n", + "\n", + "ax.imshow(dem, cmap='terrain')\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/tutorial.rst b/docs/tutorial.rst deleted file mode 100644 index 56a1c18..0000000 --- a/docs/tutorial.rst +++ /dev/null @@ -1,18 +0,0 @@ -Tutorial -======== - -Introduction ------------- - -Installing ----------- - -First steps ------------ - -Using the provided examples ---------------------------- - -Using API documentation ------------------------ -