Update documentation & READMEs (#17)

* Update documentation & READMEs

* Include the description from the devel/ directory
* Using aliases from the devel/activate-aliases.sh
  (like upytest and uipython)
* Add new sections:
  * Updating Changelog
  * Creating a New Release
* Update glossary
* Rename some RST files
* Add new alias uipython
  For the interactive IPython shell using start-up scripts from the
  .ipython directory
* Add a new alias "makedocs"
  * The "makedocs" alias calls "uv run --frozen make -C docs html"
    to update the documentation
  * Each alias contains now a comment about the purpose

Author: tomschr

changelog.d/README.rst

@@ -10,25 +10,21 @@ a changelog, in our case the :file:`CHANGELOG.rst`, is read by our *users*.
 Therefor, any description should be aimed to users instead of describing
 internal changes which are only relevant to developers.
 
-To avoid merge conflicts, we use the `Towncrier`_ package to manage our changelog.
-
 The directory :file:`changelog.d` contains "newsfragments" which are short
-ReST-formatted files.
+ReST-formatted files. Each newsfragment describes a change in the project. A change is usually from a pull request or issue.
 On release, those news fragments are compiled into our :file:`CHANGELOG.rst`.
 
-You don't need to install ``towncrier`` yourself, use the :command:`tox` command
-to call the tool.
-
 We recommend to follow the steps to make a smooth integration of your changes:
 
 #. After you have created a new pull request (PR), add a new file into the
    directory :file:`changelog.d`. Each filename follows the syntax::
 
     <ISSUE>.<TYPE>.rst
 
-   where ``<ISSUE>`` is the GitHub issue number.
-   In case you have no issue but a pull request, prefix your number with ``pr``.
-   ``<TYPE>`` is one of:
+   where ``<ISSUE>`` is the GitHub pull request or issue number.
+   If you have changes that are not associated with an issue or pull request,
+   start with a ``+`` (plus) sign and a short description
+   The ``<TYPE>`` is one of:
 
    * ``breaking``: describes a change that breaks backward compatibility.
    * ``bugfix``: fixes a reported bug.
@@ -39,13 +35,15 @@ We recommend to follow the steps to make a smooth integration of your changes:
    * ``removal``: removes obsolete or deprecated features.
    * ``infra``: improves the infrastructure, e.g. build or test system.
 
-   For example: ``123.feature.rst``, ``pr233.removal.rst``, ``456.bugfix.rst`` etc.
-   If you have changes that are not associated with an issue or pull request,
-   start with a "+" sign and a short description, for example, ``+add-json.feature.rst``. 
-   
-   Create the new file with the command::
+   For example, these are valid filenames: ``123.feature.rst``, ``456.bugfix.rst``, ``+add-json.feature.rst`` etc.
+
+   Create the new file with the command:
+
+   .. code-block:: shell
+      :caption: Create a new newsfragment file
+      :name: towncrier-create
 
-     uv run towncrier create -c "Description" 123.feature.rst
+      towncrier create -c "Description" 123.feature.rst
 
    The file is created int the :file:`changelog.d/` directory.
 
@@ -57,11 +55,11 @@ We recommend to follow the steps to make a smooth integration of your changes:
 
 #. Check your changes with::
 
-     uv run towncrier check
+     towncrier check
 
 #. Optionally, build a draft version of the changelog file with the command::
 
-    uv run towncrier build --draft
+    towncrier build --draft
 
 #. Commit all your changes and push it.
 
@@ -70,7 +68,7 @@ This finishes your steps.
 
 On release, the maintainer compiles a new :file:`CHANGELOG.rst` file by running::
 
-   uv run towncrier build
+   towncrier build
 
 This will remove all newsfragments inside the :file:`changelog.d` directory,
 making it ready for the next release.

changelog.d/_template.rst

@@ -0,0 +1,38 @@
+Development helper tools
+========================
+
+The directory :code:`devel/` contains some helper tools to make development easier:
+
+* :command:`activate-aliases.sh`
+    Activates helpful aliases for the development environment. It provides
+    shortcuts for common commands:
+
+    * :command:`docbuild`
+       The project's main command.
+    * :command:`makedocs`
+       Builds the project's documentation.
+    * :command:`towncrier`
+       Manages changelog and news entries.
+    * :command:`upytest`
+       Runs the project's test suite through pytest.
+    * :command:`uipython`
+       Starts an interactive IPython shell using start-up scripts
+       in the :file:`.ipython/` directory.
+
+    It is recommended to enable the aliases in your shell by sourcing the shell script in the root directory of the project:
+
+    .. code-block:: shell-session
+       :caption: Activating development aliases
+
+       $ source devel/activate-aliases.sh
+
+    Run the aliases in the root directory of the project to ensure they work correctly.
+
+* :command:`bump-version.sh`
+   Bumps the version of the project. To bump the minor version, use
+    :code:`bump-version.sh minor`.
+
+* :command:`lines-of-code.sh`
+   Prints a summary of code lines, comments, and blank lines in the project
+   for each file type.
+

devel/README.md

@@ -1,8 +1,12 @@
 #!/bin/bash
+# If you change this file, update the README.rst file accordingly.
 
 # For testing:
 alias upytest="uv run --frozen pytest"
 
+# For the interactive Python shell with the project's environment:
+alias uipython="uv run --frozen ipython --ipython-dir=.ipython"
+
 # For executing the project's script:
 alias docbuild="uv run --frozen docbuild"
 

devel/README.rst

@@ -26,6 +26,7 @@
 .. |gh_repo| replace:: {gh_repo_url}
 .. |gh_repo_url| replace:: `{gh_repo_slug} <{gh_repo_url}>`__
 .. |uv| replace:: :command:`uv`
+.. |gh_release| replace:: `Releases <{gh_repo_url}/releases/>`__
 """
 
 # -- General configuration

devel/activate-aliases.sh

@@ -0,0 +1,30 @@
+Creating a New Release
+======================
+
+To create a new release, follow these steps:
+
+#. Ensure that you have the latest changes from the main branch of the repository.
+#. Create a new branch for your release. The branch name should follow the format: ``release/<VERSION>``, where ``<VERSION>`` is the version number you are releasing (e.g., ``release/1.0.0``).
+#. Run the alias :command:`bump-version.sh` to update the version number in the project files. For example:
+
+   .. code-block:: shell
+      :caption: Bump the version number
+    
+       bump-version.sh minor
+
+   This will update the version number to the next minor version (e.g., from `1.0.0` to `1.1.0`).
+#. Update the changelog (see :ref:`update-changelog` for details).
+#. Commit your changes with a message that describes the release.
+#. Wait for the CI to pass. If it fails, fix the issues and commit again.
+#. If the CI passes, (squash-)merge your release branch into the main branch.
+#. Tag the commit in the ``main`` branch with the version number. The release process is triggered by this tag in the format ``MAJOR.MINOR.PATCH``. 
+
+   For example, if you are releasing version 1.1.0, you would tag the commit as follows:
+
+   .. code-block:: shell
+      :caption: Tag the release commit
+
+       $ git tag 1.1.0
+       $ git push origin 1.1.0
+
+#. Find the release in the GitHub repository under the |gh_release| section.

docs/source/conf.py

@@ -0,0 +1,9 @@
+.. _devel-helpers:
+
+Development helper tools
+------------------------
+
+.. include:: ../../../devel/README.rst
+   :start-line: 3
+
+In this documentation, we will use the aliases from now on.

docs/source/developer/create-release.rst

@@ -7,9 +7,11 @@ Developer Guide
 
    concepts
    design
-   set-environment
+   prepare-environment
    list-dependencies
    update-package
    run-testsuite
    run-ipython
+   update-changelog
+   create-release
    howto

docs/source/developer/devel-helpers.rst

@@ -5,24 +5,24 @@ If you want to get an overview of the dependencies used in the project, you can
 
 .. code-block:: shell-session
 
-   $ uv tree
-   Resolved 53 packages in 15ms
+   $ uv tree --frozen
+   Resolved 78 packages in 290ms
    docbuild
    ├── click v8.2.1
    ├── jinja2 v3.1.6
    │   └── markupsafe v3.0.2
-   ├── lxml v5.4.0
-   ├── pydantic v2.11.5
+   ├── lxml v6.0.0
+   ├── pydantic v2.11.7
    │   ├── annotated-types v0.7.0
    │   ├── pydantic-core v2.33.2
-   │   │   └── typing-extensions v4.14.0
-   │   ├── typing-extensions v4.14.0
+   │   │   └── typing-extensions v4.14.1
+   │   ├── typing-extensions v4.14.1
    │   └── typing-inspection v0.4.1
-   │       └── typing-extensions v4.14.0
+   │       └── typing-extensions v4.14.1
    ├── rich v14.0.0
    │   ├── markdown-it-py v3.0.0
    │   │   └── mdurl v0.1.2
-   │   └── pygments v2.19.1
+   │   └── pygments v2.19.2
    └── tomlkit v0.13.3
 
 This gives a tree-like structure of the dependencies, showing the main packages and their sub-dependencies. The output includes the package names and their versions, allowing you to see which libraries are being used in the project.
@@ -32,23 +32,23 @@ In case you want to list outdated dependencies, use the option ``--outdated``:
 .. code-block:: shell-session
 
    $ uv tree --outdated
-   Resolved 53 packages in 15ms
+   Resolved 78 packages in 15ms
    docbuild
    ├── click v8.2.1
    ├── jinja2 v3.1.6
    │   └── markupsafe v3.0.2
-   ├── lxml v5.4.0
-   ├── pydantic v2.11.5
+   ├── lxml v6.0.0
+   ├── pydantic v2.11.7
    │   ├── annotated-types v0.7.0
-   │   ├── pydantic-core v2.33.2 (latest: v2.34.1)
-   │   │   └── typing-extensions v4.14.0
-   │   ├── typing-extensions v4.14.0
+   │   ├── pydantic-core v2.33.2 (latest: v2.35.2)
+   │   │   └── typing-extensions v4.14.1
+   │   ├── typing-extensions v4.14.1
    │   └── typing-inspection v0.4.1
-   │       └── typing-extensions v4.14.0
+   │       └── typing-extensions v4.14.1
    ├── rich v14.0.0
    │   ├── markdown-it-py v3.0.0
    │   │   └── mdurl v0.1.2
-   │   └── pygments v2.19.1
+   │   └── pygments v2.19.2
    └── tomlkit v0.13.3
 
-As you can see, the output indicates that the package ``pydantic-core`` has a newer version available (v2.34.1), while the others are up to date.
+As you can see, the output indicates that the package ``pydantic-core`` has a newer version available (v2.35.2), while the others are up to date.