Update Documentation and add CONTRIBUTING (TopoToolbox#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

@@ -11,4 +11,7 @@ tests/__pycache__
 docs/_build/*
 
 # ignore _autosummary
-docs/_autosummary/*
+docs/_autosummary/*
+
+# ignore _temp
+docs/_temp

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!

README.md

@@ -1,6 +1,27 @@
+<p align="center">
+  <img src="https://github.com/topotoolbox/pytopotoolbox/blob/main/docs/logo.png?raw=true" alt="pytopotoolbox Logo">
+</p>
+
+-------------------
+
+![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.

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).

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/

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 -------------------------------------------------

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

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 <https://topotoolbox.wordpress.com/>`_ for Matlab and uses the API provided by `libtopotoolbox <https://topotoolbox.github.io/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 <installing>` page.
+
+If you have no experience with Python or this tool, the :doc:`tutorial <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 <examples>` contains them in the form of Jupyter Notebooks. If you want to play around with them yourself, download them from the `GitHub repository <https://github.com/TopoToolbox/pytopotoolbox/tree/main/examples>`_.
+
+API Documentation
+-----------------
+
+For further documentation regarding the functionality of this package, check out the :doc:`API documentation<api>`.
+
+Contributing
+------------
+
+If you would like to contribute to pytopotoolbox, refer to the :doc:`_temp/CONTRIBUTING`.
+
 .. toctree::
    :maxdepth: 1
-   :caption: Contents:
+   :hidden:
 
    Installing <installing>
    Tutorial <tutorial>
    Examples <examples>
    API <api>
+   Contributing <_temp/CONTRIBUTING>
 
-
-
-Indices and tables
-==================
+Indices and Tables
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

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
+myst_parser

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
+}