=========== Development =========== This chapter describes how to set up icalendar for development and to contribute changes. To start contributing changes to icalendar, you can clone the project to your file system using Git. You can `fork `_ the project first and clone your fork, too. .. code-block:: shell git clone https://github.com/collective/icalendar.git cd icalendar Install Python -------------- You will need a version of Python installed on your system to run the tests and execute the code. The latest version of Python 3 should work and will be enough to get you started. If you like to run the tests across multiple Python versions, then the following setup process should work the same. Install tox ----------- First, install `tox `_. .. code-block:: shell pip install tox From now on, tox will manage Python versions and test commands for you. Run tests --------- tox manages all test environments in all Python versions. To run all tests in all environments, run the command ``tox``. .. code-block:: shell tox You might not have all Python versions installed or you may want to run a specific one. The following command show how to run tox with Python 3.12: .. code-block:: shell tox -e py312 .. seealso:: tox's `documentation `_. Code style ---------- icalendar strives towards a common code style. You can run the following command to automatically format the code. .. code-block:: shell tox -e ruff Activate a tox environment -------------------------- If you'd like to activate a specific tox virtual environment, use the following command, replacing the Python version accordingly. .. code-block:: shell source .tox/py312/bin/activate Install icalendar manually -------------------------- The best way to test the package is to use tox as described above. However, if you can't install tox, or you'd like to use your local copy of icalendar in another Python environment, this section describes how to use your installed version of Python and pip. .. code-block:: shell cd src/icalendar python -m pip install -e . The above commands install icalendar and its dependencies in your Python environment so that you can access local changes. If tox fails to install icalendar during its first run, you can activate the environment in the :file:`.tox` folder and manually set up icalendar as shown above. To verify installation, launch a Python interpreter, and issue the following statements. .. code-block:: pycon Python 3.12.0 (main, Mar 1 2024, 09:09:21) [GCC 13.2.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import icalendar >>> icalendar.Calendar() VCALENDAR({}) .. _documentation-prerequisites: Documentation prerequisites --------------------------- Documentation builds require that you install GNU Make and uv. Make ```` ``make`` is used to provide an interface to developers to perform repetitive tasks with a single command. ``make`` comes installed on most Linux distributions. On macOS, you must first [install Xcode](https://developer.apple.com/xcode/resources/), then install its command line tools. On Windows, it is strongly recommended to [Install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install), which will include ``make``. Finally, it is a good idea to update your system's version of ``make``, because some distributions, especially macOS, have an outdated version. Use your favorite search engine or trusted online resource for how to update ``make``. uv `` `uv `_ is used for installing Python, creating a Python virtual environment, and managing dependencies for documentation. Install uv. Read the console output for further instructions, and follow them, if needed. .. tab-set:: .. tab-item:: macOS, Linux, and Windows with WSL .. code-block:: shell curl -LsSf https://astral.sh/uv/install.sh | sh .. tab-item:: Windows .. code-block:: shell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" .. seealso:: [Other {term}`uv` installation methods](https://docs.astral.sh/uv/getting-started/installation/) Documentation builds -------------------- All build and check commands use the file :file:`Makefile` at the root of the repository. To see descriptions of the builds, use the following command. .. code-block:: shell make help Else you can open the :file:`Makefile` file to see other build formats. The following sections describe the most frequently used ``make`` commands. All ``make`` commands that build documentation will - create a Python virtual environment, and - install requirements. ``html`` ```````` To build the documentation as HTML, run the following command. .. code-block:: shell make html You can now open the output from ``docs/_build/html/index.html``. ``livehtml`` ```````````` ``livehtml`` rebuilds documentation as you edit its files, with live reload in the browser. .. code-block:: shell make livehtml The console will give you the URL to open in a web browser. .. code-block:: console [sphinx-autobuild] Serving on http://127.0.0.1:8050 ``linkcheckbroken`` ``````````````````` ``linkcheckbroken`` checks all links, returning a list of only broken links. .. code-block:: shell make linkcheckbroken Open `docs/_build/linkcheck/output.txt` for the entire list of links that were checked and their result. ### `vale` `vale` checks for American English spelling, grammar, and syntax, and follows the Microsoft Writing Style Guide. See {ref}`authors-english-label` for configuration. .. code-block:: shell make vale See the output on the console for suggestions. ``clean`` ````````` ``clean`` removes all builds and cached files of the documentation. Use this command before a build to troubleshoot issues with edits not showing up and to ensure that cached files do not hide errors in the documentation. .. code-block:: shell make clean ``clean-python`` ```````````````` ``clean-python`` cleans the documentation build directory and Python virtual environment. Use this command when packages that you have installed in your virtual environment yield unexpected results. .. code-block:: shell make clean-python ``apidoc`` `````````` ``apidoc`` generates source documentation files from which Sphinx will render the API documentation. .. code-block:: shell make apidoc When editing icalendar's Python source code, use `Google Python Style Guide `_ for the docstring format. The following is an example that will render properly. .. code-block:: python def fetch_smalltable_rows( table_handle: smalltable.Table, keys: Sequence[bytes | str], require_all_keys: bool = False, ) -> Mapping[bytes, tuple[str, ...]]: """A one-line summary of the module or program, terminated by a period. Leave one blank line. The rest of this docstring should contain an overall description of the module or program. Optionally, it may also contain a brief description of exported classes and functions and/or usage examples. Args: table_handle: An open ``smalltable.Table`` instance. keys: A sequence of strings representing the key of each table row to fetch. String keys will be UTF-8 encoded. require_all_keys: If True only rows with values set for all keys will be returned. Returns: A dict mapping keys to the corresponding table row data fetched. Each row is represented as a tuple of strings. For example: .. code-block:: python {b'Serak': ('Rigel VII', 'Preparer'), b'Zim': ('Irk', 'Invader'), b'Lrrr': ('Omicron Persei 8', 'Emperor')} Returned keys are always bytes. If a key from the keys argument is missing from the dictionary, then that row was not found in the table (and require_all_keys must have been False). Raises: IOError: An error occurred accessing the smalltable. Example: The following is an example of using ``fetch_smalltable_rows``. .. code-block: pycon >>> fetch_smalltable_rows(my_table_handle, (b'Serak', b'Zim', b'Lrrr')) {b'Serak': ('Rigel VII', 'Preparer'), b'Zim': ('Irk', 'Invader'), b'Lrrr': ('Omicron Persei 8', 'Emperor')} """ .. seealso:: `sphinx-apidoc `_ ``vale`` ```````` :term:`Vale` is used to check American English spelling, grammar, and syntax, and style guides. .. code-block:: shell make vale Observe the output and adjust Vale's configuration, as described in the next section. Advanced Vale usage +++++++++++++++++++ You can pass options to Vale in the ``VALEOPTS`` and ``VALEFILES`` environment variables. In the following example, you can run Vale to display warnings or errors only, not suggestions, in the console on a single file. .. code-block:: shell make vale VALEOPTS="--minAlertLevel='warning'" VALEFILES="docs/index.md" The command ``make vale`` automatically installs Vale into your Python virtual environment—which is also created via any documentation ``Makefile`` commands—when you invoke it for the first time. Vale has `integrations `_ with various IDEs. Integration might require installing Vale using operating system's package manager. - `JetBrains `_ - `Vim `_ - `VS Code `_ icalendar configures Vale in three places: - :file:`.vale.ini` is Vale's configuration file. This file allows overriding rules or changing their severity. It's configured to use the `Microsoft Writing Style Guide `_ for its ease of use—especially for non-native English readers and writers—and attention to non-technical audiences. - :file:`Makefile` passes options to the ``vale`` command, such as the files Vale checks. - icalendar documentation uses a custom spelling dictionary, with accepted and rejected spellings in :file:`docs/styles/config/vocabularies/icalendar/`. Authors should add new words and proper names using correct casing to :file:`docs/styles/config/vocabularies/icalendar/accept.txt`, sorted alphabetically and case-insensitive. If Vale does not reject a spelling that should be rejected, then you can add it to {file}`docs/styles/config/vocabularies/icalendar/reject.txt`. - You can add additional spellings to accept or reject in their respective files inside the {file}`docs/styles/config/vocabularies/Base/` folder. Because it's difficult to automate good American English grammar and syntax, it's not strictly enforced. You can add spellings to Vale's configuration, and submit a pull request. This is an easy way to become a contributor to icalendar.