Merge branch 'main' into rfc-7529

.github/workflows/rtd-pr-preview.yml

@@ -0,0 +1,26 @@
+# .github/workflows/rtd-pr-preview.yml
+name: readthedocs/actions
+on:
+  pull_request_target:
+    types:
+      - opened
+    # Execute this action only on PRs that touch
+    # documentation files.
+    paths:
+      - "docs/**"
+      - "*.rst"
+      - "src/icalendar/*.py"
+      - .readthedocs.yaml
+      - requirements_docs.txt
+
+permissions:
+  pull-requests: write
+
+jobs:
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "icalendar"
+          single-version: "true"

.github/workflows/tests.yml

@@ -22,7 +22,7 @@ jobs:
         - ["3.9",   "py39"]
         - ["3.10",  "py310"]
         - ["pypy-3.9", "pypy3"]
-        - ["3.10",  "docs"]
+#        - ["3.10",  "docs"]  # disable as readthedocs builds it
         - ["3.11",  "py311"]
         - ["3.12",  "py312"]
 
@@ -47,13 +47,13 @@ jobs:
         pip install tox coveralls coverage-python-version
     - name: Test
       run: tox -e ${{ matrix.config[1] }}
-    - name: Upload coverage data to coveralls.io
-      run: coveralls --service=github || which coveralls
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        COVERALLS_REPO_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-        COVERALLS_FLAG_NAME: ${{ matrix.config[1] }}
-        COVERALLS_PARALLEL: true
+    - name: Coveralls Parallel
+      uses: coverallsapp/github-action@v2
+      with:
+        flag-name: run-${{ matrix.config[1] }}
+        parallel: true
+        file: coverage.xml
+        allow-empty: true
 
   coverage:
     # parallel test coverage upload
@@ -64,15 +64,12 @@ jobs:
     # see https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#example-not-requiring-successful-dependent-jobs
     if: ${{ always() }}
     runs-on: ubuntu-latest
-    container: python:3-slim
     steps:
-    - name: Install dependencies
-      run: pip3 install --upgrade coveralls
-    - name: Upload coverage
-      run: coveralls --service=github --finish || which coveralls
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        COVERALLS_REPO_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+    - name: Coveralls Finished
+      uses: coverallsapp/github-action@v2
+      with:
+        parallel-finished: true
+        format: cobertura
 
   deploy-tag-to-pypi:
     # only deploy on tags, see https://stackoverflow.com/a/58478262/1320237
@@ -142,5 +139,9 @@ jobs:
       name: github-release
     steps:
       - uses: actions/checkout@v4
-      - name: create release
+      - name: Create GitHub release from tag
         uses: ncipollo/release-action@v1
+        with:
+          allowUpdates: true
+          body: "To view the changes, please see the [Changelog](https://icalendar.readthedocs.io/en/latest/changelog.html). This release can be installed from [PyPI](https://pypi.org/project/icalendar/#history)."
+          generateReleaseNotes: false

.readthedocs.yml

@@ -16,9 +16,17 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
-
-python:
-  install:
-    - requirements: requirements_docs.txt
-    - method: pip
-      path: .
+  commands:
+    # Cancel building pull requests when there aren't changes in the docs directory or YAML file.
+    # You can add any other files or directories that you'd like here as well,
+    # like your docs requirements file, or other files that will change your docs build.
+    #
+    # If there are no changes (git diff exits with 0) we force the command to return with 183.
+    # This is a special exit code on Read the Docs that will cancel the build immediately.
+    - |
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- . docs/ src/icalendar/*.py *.rst .readthedocs.yaml requirements_docs.txt ':!src/icalendar/fuzzing' ':!src/icalendar/tests' ':!src/icalendar/timezone';
+      then
+        exit 183;
+      fi
+    - pip install -r requirements_docs.txt
+    - cd docs && make rtd-pr-preview

CHANGES.rst

@@ -7,16 +7,18 @@ Changelog
 Minor changes:
 
 - Test that all code works with both ``pytz`` and ``zoneinfo``.
+- Add message to GitHub release, pointing to the changelog
 - Make coverage report submission optional for pull requests
 - Parallelize coverage
 - Rename ``master`` branch to ``main``, see `Issue
   <https://github.com/collective/icalendar/issues/627>`_
-- Update ``docs/usage.rst`` to use zoneinfo instead of pytz.  
+- Update ``docs/usage.rst`` to use zoneinfo instead of pytz.
 - Added missing public classes and functions to API documentation.
 - Improved namespace management in the ``icalendar`` directory.
 - Add Python version badge and badge for test coverage
 - Remove 4.x badge
 - Update list of ``tox`` environments
+- Use Coveralls' GitHub Action
 
 Breaking changes:
 
@@ -66,7 +68,11 @@ New features:
 - Allows selecting components with ``walk(select=func)`` where ``func`` takes a
   component and returns ``True`` or ``False``.
 - Add compatibility to :rfc:`7529`, adding ``vMonth`` and ``vSkip``
-- Add `sphinx-autobuild` for `livehtml` Makefile target.
+- Add ``sphinx-autobuild`` for ``livehtml`` Makefile target.
+- Add pull request preview on Read the Docs, building only on changes to documentation-related files.
+- Add link to pull request preview builds in the pull request description only when there are changes to documentation-related files.
+- Add documentation of live HTML preview of documentation and clean up of ``install.rst``.
+- Add ``sphinx-copybutton`` to allow copying code blocks with a single click of a button.
 
 Bug fixes:
 

README.rst

@@ -156,7 +156,7 @@ By default and since 6.0.0, ``zoneinfo`` timezones are created.
     >>> dt.tzinfo
     ZoneInfo(key='Europe/Vienna')
 
-If you would like to continue to receive ``pytz`` timezones in as parse results,
+If you would like to continue to receive ``pytz`` timezones in parse results,
 you can receive all the latest updates, and switch back to earlier behavior:
 
 .. code:: python

docs/Makefile

@@ -16,7 +16,7 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext livehtml
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext livehtml rtd-pr-preview
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -166,3 +166,6 @@ livehtml:
 	--ignore "*.swp" \
 	--port 8050 \
 	-b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+rtd-pr-preview:  ## Build pull request preview on Read the Docs
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/

docs/conf.py

@@ -20,7 +20,8 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.coverage',
-    'sphinx.ext.viewcode'
+    'sphinx.ext.viewcode',
+    'sphinx_copybutton'
 ]
 source_suffix = '.rst'
 master_doc = 'index'

docs/install.rst

@@ -1,14 +1,18 @@
 Installing iCalendar
 ====================
 
-To install the icalendar package, use::
+To install the icalendar package, use:
 
-  pip install icalendar
+.. code-block:: shell
+
+    pip install icalendar
 
 If installation is successful, you will be able to import the iCalendar
-package, like this::
+package, like this:
+
+.. code-block:: pycon
 
-  >>> import icalendar
+    >>> import icalendar
 
 Development Setup
 -----------------
@@ -19,7 +23,7 @@ using Git.
 You can `fork <https://github.com/collective/icalendar/fork>`_
 the project first and clone your fork, too.
 
-.. code-block:: bash
+.. code-block:: shell
 
     git clone https://github.com/collective/icalendar.git
     cd icalendar
@@ -39,7 +43,7 @@ Install Tox
 
 First, install `tox <https://pypi.org/project/tox/>`_..
 
-.. code-block:: bash
+.. code-block:: shell
 
     pip install tox
 
@@ -53,7 +57,7 @@ Running Tests
 
 To run all tests in all environments, simply run ``tox``
 
-.. code-block:: bash
+.. code-block:: shell
 
     tox
 
@@ -63,7 +67,7 @@ Have a look at the `documentation
 <https://tox.wiki/en/latest/example/general.html#selecting-one-or-more-environments-to-run-tests-against>`__.
 This is how you can run ``tox`` with Python 3.9:
 
-.. code-block:: bash
+.. code-block:: shell
 
     tox -e py39
 
@@ -73,7 +77,7 @@ Accessing a ``tox`` environment
 If you like to enter a specific tox environment,
 you can do this:
 
-.. code-block:: bash
+.. code-block:: shell
 
     source .tox/py39/bin/activate
 
@@ -93,7 +97,7 @@ this section explains how to do it.
 You can install the local copy of ``icalendar`` with ``pip``
 like this:
 
-.. code-block:: bash
+.. code-block:: shell
 
     cd icalendar
     python -m pip install -e .
@@ -106,40 +110,47 @@ manually setup ``icalendar`` like this.
 
 Try it out:
 
-.. code-block:: python
+.. code-block:: pycon
 
     Python 3.9.5 (default, Nov 23 2021, 15:27:38)
     Type "help", "copyright", "credits" or "license" for more information.
     >>> import icalendar
     >>> icalendar.__version__
     '5.0.13'
 
-Building the documentation
---------------------------
+Build the documentation
+-----------------------
 
-To build the documentation follow these steps:
+To build the documentation, follow these steps:
 
-.. code-block:: bash
+.. code-block:: shell
 
-    $ source .tox/py39/bin/activate
-    $ pip install -r requirements_docs.txt
-    $ cd docs
-    $ make html
+    source .tox/py311/bin/activate
+    pip install -r requirements_docs.txt
+    cd docs
+    make html
 
-You can now open the output from ``_build/html/index.html``. To build the
-presentation-version use ``make presentation`` instead of ``make html``. You
-can open the presentation at ``presentation/index.html``.
+You can now open the output from ``_build/html/index.html``.
 
-You can also use ``tox`` to build the documentation:
+To build the documentation, view it in a web browser, and automatically reload changes while you edit documentation, use the following command.
 
-.. code-block:: bash
+.. code-block:: shell
 
-    cd icalendar
-    tox -e docs
+    make livehtml
+
+Then open a web browser at `http://127.0.0.1:8050 <http://127.0.0.1:8050>`_.
 
-If you would like to serve the documentation and access it from your browser,
-you can run the HTTP server:
+To build the presentation-version use  the following command.
 
-.. code-block:: bash
+.. code-block:: shell
 
-    python3 -m http.server -d docs/_build/html/
+    make presentation
+
+You can open the presentation at ``presentation/index.html``.
+
+You can also use ``tox`` to build the documentation:
+
+.. code-block:: shell
+
+    cd icalendar
+    tox -e docs

requirements_docs.txt

@@ -1,4 +1,5 @@
 Sphinx>=1.2.3
 sphinx_rtd_theme
 sphinx-autobuild
+sphinx-copybutton
 .

tox.ini

@@ -16,6 +16,7 @@ commands =
     coverage run --source=src/icalendar --omit=*/tests/hypothesis/* --omit=*/tests/fuzzed/* --module pytest []
     coverage report
     coverage html
+    coverage xml
 
 [testenv:nopytz]
 # install with dependencies
@@ -34,6 +35,7 @@ commands =
     coverage run --source=src/icalendar --omit=*/tests/hypothesis/* --omit=*/tests/fuzzed/* --module pytest []
     coverage report
     coverage html
+    coverage xml
 
 [testenv:docs]
 deps =