Update installation instructions in README and docs (TopoToolbox#87)

The pip installation instructions are added to the README and to the documentation landing page. The instructions for developers on setting up a development environment and running tests and lints are moved to a new page of Developer Documentation at docs/dev.rst.

README.md

@@ -4,10 +4,10 @@
 
 -------------------
 
-![GitHub Release](https://img.shields.io/github/v/release/topotoolbox/pytopotoolbox)
-![PyPI - Version](https://img.shields.io/pypi/v/topotoolbox)
+[![GitHub Release](https://img.shields.io/github/v/release/topotoolbox/pytopotoolbox)](https://github.com/TopoToolbox/pytopotoolbox/releases/tag/v0.0.1)
+[![PyPI - Version](https://img.shields.io/pypi/v/topotoolbox)](https://pypi.org/project/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)
+[![GitHub License](https://img.shields.io/github/license/topotoolbox/pytopotoolbox)](https://github.com/TopoToolbox/pytopotoolbox#GPL-3.0-1-ov-file)
 
 # pytopotoolbox
 
@@ -23,97 +23,20 @@ To get started head to [pytopotoolbox/tutorial](https://topotoolbox.github.io/py
 
 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
+## Installation
 
-For any operating system, install the following:
+TopoToolbox is available in the [Python Package
+Index](https://pypi.org/project/topotoolbox/). With Python version 3.10
+or later and `pip` installed, you can run
 
-- **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`
-
-    ```bash
-    pip install dist_name.whl
-    ```
-
-- **Installing directly from the repository:**
-
-    ```bash
-    cd path/to/pytopotoolbox
-    pip install .
-    ```
-
-- **Generating distribution archives**
-
-    ```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`.
-
-    ```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](https://visualstudio.microsoft.com/downloads/).
-        - 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:
-
-        ```bash
-        cd path\to\pytopotoolbox
-        pip install .
-        ```
-
-- **Generating distribution archives**
-
-    Open the 'x64 Native Tools Command Prompt for VS 2022' Terminal and run:
-
-    ```bash
-    cd path\to\pytopotoolbox
-    py -m pip install --upgrade build
-    py -m build
-    ```
-
-### Mac
-
-[work in progress]
-
-## Testing and Linting
-
-To run the tests for this package, run:
-
-```bash
-cd path/to/pytopotoolbox
-pytest
 ```
-
-To run the linting locally, use:
-
-```bash
-cd path/to/pytopotoolbox
-flake8 src/topotoolbox
-mypy --ignoremissing-imports src/topotoolbox
+pip install topotoolbox
 ```
 
+to install the latest release from the Python Package Index. If you
+run into problems with installation, please open an
+[issue](https://github.com/TopoToolbox/pytopotoolbox/issues/new/).
+
 ## Contributing
 
 If you would like to contribute to pytopotoolbox, check out the [Contribution Guidelines](./CONTRIBUTING.md).

docs/dev.rst

@@ -0,0 +1,66 @@
+Developer Documentation
+=======================
+
+To set up pytopotoolbox for development, first make sure you have `set
+up Git
+<https://docs.github.com/en/get-started/getting-started-with-git>`_,
+`fork the repository on GitHub
+<https://github.com/TopoToolbox/pytopotoolbox/fork>`_ then use ``git
+clone https://github.com/$YOUR_USERNAME/pytopotoolbox`` to download
+your fork of the repository, where you have replaced ``$YOUR_USERNAME``
+with your GitHub username.
+
+To ensure you have a development environment that is consistent with
+other developers and with our continuous integration and testing
+setup, it is a good idea to set up a `virtual environment
+<https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/>`_
+in Python. You can then install the developer environment by running
+
+.. code-block:: bash
+		
+    pip install -r requirements.txt .
+
+within the top-level directory of the repository.
+
+Now you can make changes within pytopotoolbox. To rebuild
+pytopotoolbox after making changes, you'll need to run
+
+.. code-block:: bash
+		
+    pip install .
+
+You can run the tests with
+
+.. code-block:: bash
+		
+   python -m pytest
+
+and the linter and type checks with
+
+.. code-block:: bash
+		
+    pylint --rcfile=pyproject.toml src/topotoolbox
+    mypy --ignoremissing-imports src/topotoolbox
+
+It is a good idea to run the linter and type checks before making a
+pull request to pytopotoolbox, because failing lints or type checks
+will cause a test failure that must be fixed before your contribution
+can be accepted.
+
+
+Development environment on Windows
+----------------------------------
+
+pytopotoolbox requires C/C++ files to be compiled. If you are
+developing on Windows, there are a few extra steps to ensure that you
+have access to the Windows C/C++ toolchain.
+
+1. Install the `Developer Command Prompt for VS 2022 <https://visualstudio.microsoft.com/downloads/>`_.
+
+   * 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 opened command prompt, navigate to the pytopotoolbox directory and follow the instructions above for installing the development environment.

docs/index.rst

@@ -8,14 +8,17 @@ This Python library is based on the `TopoToolbox <https://topotoolbox.wordpress.
 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.
+TopoToolbox is on PyPI, so you can run
 
-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.
+.. code-block:: bash
 
-Examples
---------
+    pip install topotoolbox
 
-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>`_.
+to obtain the latest version.
+
+Once you have the package installed, the :doc:`tutorial <tutorial>` provides a basic walkthrough of loading and displaying a digital elevation model with TopoToolbox.
+
+Further examples of TopoToolbox functionality can be found in the :doc:`example notebooks <examples>`, which can also be downloaded from the `GitHub repository <https://github.com/TopoToolbox/pytopotoolbox/tree/main/examples>`_.
 
 API Documentation
 -----------------
@@ -31,15 +34,15 @@ If you would like to contribute to pytopotoolbox, refer to the :doc:`_temp/CONTR
    :maxdepth: 1
    :hidden:
 
-   Installing <installing>
    Tutorial <tutorial>
    Examples <examples>
    API <api>
    Contributing <_temp/CONTRIBUTING>
+   Developer Documentation <dev>
 
 Indices and Tables
 ------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
+* :ref:`search`