updates docs (#77)

* improve the documentation on how to update dependencies
* make it even more clear in the docs that requirements must be frozen
* mention the optional usage of devcontainers
* fix typos
* update sphinx

.pre-commit-config.yaml

@@ -16,7 +16,7 @@ repos:
         args: ["poetry.lock"]
 
   - repo: https://github.com/pycqa/isort
-    rev: 5.11.5
+    rev: 5.13.2
     hooks:
       - id: isort
         name: isort (python)
@@ -47,7 +47,7 @@ repos:
         types: [python]
 
   - repo: https://github.com/PyCQA/bandit
-    rev: "1.7.5"
+    rev: "1.7.9"
     hooks:
       - id: bandit
         files: "^req2flatpak.py$"

README.rst

@@ -25,15 +25,19 @@ using pip.
 Getting Started
 ---------------
 
-Run ``pip install req2flatpak``
-to install the latest release of req2flatpak.
+Install req2flatpak using pip (or any other python package installer),
+e.g., by running ``pip install req2flatpak``.
 
-It is possible to use req2flatpak from the commandline,
-as well as programmatically from a python script.
+Prepare a ``requirements.txt`` file with the packages that you want to install as part of a flatpak build.
+You need to specify exact versions for all the packages including their dependencies.
+(Various tools exist to help creating such a requirements file with fully resolved dependencies and frozen package versions;
+for example, you can use
+`pip-compile <https://pypi.org/project/pip-tools/>`_ or 
+`poetry export <https://pypi.org/project/poetry-plugin-export/>`_ to export a suitable ``requirements.txt`` file).
 
-Commandline usage means you can invoke req2flatpak’s commandline interface
-as follows, in order to generate a ``flatpak-builder`` build module
-from given python package requirements:
+Run req2flatpak. 
+For example, run this command to generate a ``flatpak-builder`` build module
+from your ``requirements.txt`` file:
 
 .. code:: bash
 
@@ -46,17 +50,17 @@ choose appropriate downloads for the specified target platforms,
 and generate a flatpak-builder build module.
 The module, if included in a flatpak-builder build manifest,
 will install the required packages using pip.
-
 The commandline option to define target platforms uses the format ``<pythonversion>-<architecture>``.
 To learn more about available commandline options,
 run ``req2flatpak.py --help``.
 
-Programmatic usage is also possible.
-This means you can invoke functionality from req2flatpak in your own python script,
-allowing you to tweak the desired behavior in many ways.
-The `documentation <https://johannesjh.github.io/req2flatpak/>`__
-describes req2flatpak's python api and includes code examples
-to help you get started quickly.
+Note that programmatic usage of req2flatpak is also possible.
+This means you can write a python script to invoke req2flatpak,
+which allows to tweak the desired behavior in many ways.
+
+Go read the `documentation <https://johannesjh.github.io/req2flatpak/>`__
+to learn more about req2flatpak's commandline and Python APIs.
+The documentation includes further examples to help you get started quickly.
 
 
 Documentation

docs/source/development.rst

@@ -37,21 +37,23 @@ to make sure req2flatpak stays compatible with older targeted python versions.
 Setting up a Development Environment
 ------------------------------------
 
-Simply clone/open req2flatpak in the IDE of your choice.
+Clone the req2flatpak git repository in the IDE of your choice.
 Features and languages that the IDE should ideally support include:
 
-* python
+* python,
+* poetry (for managing req2flatpak's dependencies in a virtual environment),
+* devcontainers (optionally, for working inside a docker image instead of your local system), as well as
+* restructured text (optionally, for writing documentation).
 
-* poetry for managing req2flatpak's dependencies in a virtual environment
 
-* restructured text (``*.rst``) for writing documentation
+Install poetry and pre-commit using the python installer of your choice, 
+e.g., by running ``pipx install poetry`` and ``pipx install pre-commit``.
 
+Run ``poetry install --with lint --with docs --all-extras``.
+This will install all the python packages you need into a python virtual environment.
 
-Installing Dependencies
------------------------
-
-req2flatpak depends on very few other software packages, as documented in req2flatpak's ``pyproject.toml`` file.
-Run ``poetry install`` to install these packages into a python virtual environment.
+Run ``pre-commit install``.
+This will initialize pre-commit in your local development repository.
 
 
 Running a Development Version
@@ -118,7 +120,7 @@ Use `pre-commit <https://pre-commit.com/>`__ to prettify and lint the code befor
 
    # to install pre-commit on your system,
    # follow instructions from https://pre-commit.com/, for example:
-   pip install pre-commit  # install pre-commit using pip
+   pipx install pre-commit
 
    # to install the pre-commit git hooks in the cloned req2flatpak repo
    pre-commit install  # activates pre-commit in the current git repo
@@ -137,68 +139,41 @@ We welcome your contributions even if your workflow differs from what we recomme
 Updating Dependencies
 ---------------------
 
-There are three categories of dependencies that can be found in this repository:
-*Github Actions*, *Poetry* and *pre-commit hooks*.
-Currently there is no programmatic way to update the github actions we depend on.
-One has to manually update the commit hashes used.
-
-Poetry dependencies
-```````````````````
-
-Poetry differentiates between direct and indirect dependencies.
-Direct dependencies are specified in ``pyproject.toml`` -- usually with a fixed version.
-Updating these can introduce bugs through breaking changes in the API exposed by
-these dependencies. That's why we'll focus on updating indirect dependencies first.
-Running the following and committing the resulting changes to ``poetry.lock`` will
-do the trick provided that set up *pre-commit* according to this guide.
-
-
-.. code:: bash
-
-   # 1. Update indirect dependencies (stored in poetry.lock)
-   poetry update
-
-   # 2. Stage and commit (runs pre-commit hooks)
-
+There are multiple categories of dependencies that can be found in this repository:
+CI, Poetry and pre-commit hooks.
 
-Direct dependencies are updated by changing the version specified in ``pyproject.toml``.
-You will have to manually identify the latest version for a package by opening
-its project page on `pypi <https://pypi.org/project/{name}/>`_.
-
-
-.. code:: bash
-
-   # 1. Determine latest version of a package.
-   # 2. Update version requirement in `pyproject.toml`
-   # 3. Update `poetry.lock` (`--no-update` will prevent updating indirect dependencies)
-   poetry lock --no-update
-
-   # 4. Install newest version (adjust options to your dev env)
-   poetry install --with lint --all-extras
-
-   # 5. Stage and commit (runs pre-commit hooks)
+CI dependencies
+```````````````
 
+Github actions and workflows contain hardcoded versions of container images and packages.
+See the ``.github`` folder.
+Currently there is no programmatic way to update the github actions we depend on.
+One has to manually update the versions and/or commit hashes.
 
-Pre-commit hooks
-````````````````
+The devcontainer configuration file also contains versions,
+these are also manually kept up-to-date.
+See the ``.devcontainer`` folder.
 
-Pre-commit hooks require a bit more steps to update because they are partially
-synced with the versions specified in ``poetry.lock``.
 
+Poetry and pre-commit dependencies
+``````````````````````````````````
 
-.. code:: bash
+First update poetry dependencies, 
 
-   # 1. Update pre-commit hooks
-   pre-commit autoupdate --freeze
+#. Manually bump the version constraints in the ``pyproject.toml`` file.
+#. Run ``poetry update --with lint`` to update installed packages and write the lock file.
+#. Stage changes by running ``git add pyproject.toml poetry.lock``.
 
-   # 2. Stage `.pre-commit-config.yaml`
-   git add .pre-commit-config.yaml
 
-   # 3. Sync with poetry
-   pre-commit run
+Then update pre-commit dependencies,
 
-   # 4. Remove `frozen: x.x.x` comments for unfrozen dependencies
-   # 5. Stage and commit (runs pre-commit hooks)
+#. Run ``pre-commit install`` just to be sure that pre-commit is properly initialized.
+#. Run ``pre-commit autoupdate --freeze`` to update pre-commit's packages.
+#. Stage changes by running ``git add .pre-commit-config.yaml``.
+#. Run ``pre-commit run`` to sync package versions from poetry to pre-commit. Note that this is a one-way-sync, i.e., `sync_with_poetry <https://github.com/floatingpurr/sync_with_poetry>`_ will copy package versions from the poetry lock file into the pre-commit yaml file.
+#. Stage changes by running ``git add .pre-commit-config.yaml``.
+#. run ``pre-commit run`` to verify that pre-commit now happily leaves all files unchanged.
+#. Stage and commit all changes.
 
 
 Publishing a Release