summaryrefslogtreecommitdiffstats
path: root/share/extensions/docs/dev
diff options
context:
space:
mode:
Diffstat (limited to 'share/extensions/docs/dev')
-rw-r--r--share/extensions/docs/dev/getting-started.rst148
-rw-r--r--share/extensions/docs/dev/index.rst8
2 files changed, 156 insertions, 0 deletions
diff --git a/share/extensions/docs/dev/getting-started.rst b/share/extensions/docs/dev/getting-started.rst
new file mode 100644
index 0000000..63d8a46
--- /dev/null
+++ b/share/extensions/docs/dev/getting-started.rst
@@ -0,0 +1,148 @@
+Getting started with developing inkex
+=====================================
+
+.. highlight:: bash
+
+.. warning::
+
+ This document is tailored for contributors to the inkex package and core extensions.
+
+ Extension authors should look here: :ref:`authors-tutorial`
+
+Repository setup
+----------------
+
+It is possible to synchronize a fork with the extensions repository - whenever a branch in the
+mirrored repository is updated, your fork will be updated too (usually with a delay of up to one
+hour). See `Settings -> Repository -> Mirroring Repositories` and add a "Pull" mirror.
+
+.. warning::
+
+ If you use this method, **do not** add commits to branches that should be synced
+ (such as `master`).
+ Depending on the exact settings of the mirroring option, you will either lose your changes,
+ lose the synchronisation or run into a messed up branch history.
+
+Always check out submodules as well::
+
+ git submodule update && git submodule init
+
+Python setup
+------------
+
+On every operating system, you need a working Python environment. Currently, inkex is tested
+against Python 3.7-3.10.
+
+inkex manages its dependencies using `poetry <https://python-poetry.org/docs/>`_. It can be installed using::
+
+ pip install poetry
+
+Install the dependencies and the pre-commit hook::
+
+ poetry install
+ pre-commit install
+
+Testing changes in Inkscape
+---------------------------
+
+Most of the time, calling the python file of the extension directly and through unit tests is
+sufficient. In some cases, the interaction between Inkscape and the extension should be tested,
+though.
+
+Assuming you have managed to make Inkscape look in the correct folder for the extensions (see hints
+for different operating systems below), the python
+file of an extension is reloaded every time the extension is run. For changes to the inx file or
+the command line parameters of the extension (as defined in the
+:func:`~inkex.base.InkscapeExtension.add_arguments` method) you need to restart Inkscape.
+
+Developing extensions on Windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+.. highlight:: batch
+
+To test extensions with a given Inkscape version, download the 7z archive of that version,
+unarchive it and delete the ``inkscape\share\extensions`` folder. Next, create a symlink in that
+folder from an administrative command prompt::
+
+ cd [directory of the unzipped Inkscape folder]
+ mklink /D share\extensions C:\path\to\your\fork
+
+If you start ``bin\inkscape`` now, the extensions are loaded from your fork.
+
+Developing extensions on Linux
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. highlight:: bash
+
+A very similar path to Windows can be used when working off an appimage build.
+
+Extract the appimage into a new folder called ``squashfs-root``::
+
+ /path/to/appimage --appimage-extract
+ squashfs-root/AppRun --system-data-directory
+
+This prints the location of the extensions folder. Create a symlink to your repo there and run::
+
+ squashfs-root/AppRun
+
+Trying / Changing a merge request locally
+-----------------------------------------
+
+Add this to ``git config -e`` (only once)::
+
+ [remote "upstream"]
+ url = git@gitlab.com:inkscape/extensions.git
+ fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
+ [alias]
+ mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' -
+
+Check out the merge request !123::
+
+ git mr upstream 123
+
+Push changes to the source branch ``source-branch-name`` of fork in the namespace (typically the
+author's username) ``xyz``::
+
+ git push git@gitlab.com:xyz/extensions.git mr-origin-123:source-branch-name
+
+
+Adding/Updating dependencies
+----------------------------
+
+.. highlight:: bash
+
+The *direct* dependencies of inkex are declared in the ``pyproject.toml`` file.
+
+There is also a lockfile named ``poetry.lock`` which has *all* the dependencies
+(direct, dependencies of direct, dependencies of dependencies of direct and so on till the leaf dependencies)
+pinned to specific versions (versions which were compatible the last time lockfile was updated).
+
+To update all the dependencies in the lockfile to latest compatible versions, enter::
+
+ poetry lock
+
+To add/update a particular dependency, add it to ``pyproject.toml`` manually. The dependency should be declared in the
+``[tool.poetry.dependencies]`` TOML table, while a dependency required only during development of inkex should be declared in
+``[tool.poetry.dev-dependencies]``.
+
+Then update the lockfile using::
+
+ poetry lock
+
+Alternatively, you can add a dependency and update the lockfile in a single command::
+
+ poetry add "lxml@^4.5.0" --lock
+
+Both the ``pyproject.toml`` and ``poetry.lock`` are to be committed to the repository.
+
+.. note::
+
+ You don't need to install the dependencies to add/update them. So, the commands above don't install anything.
+ However, if you are using poetry to manage the environment, and want to also install the dependencies,
+ remove the ``--lock`` options from the commands and use ``poetry update`` instead of ``poetry lock``.
+
+.. note::
+
+ Dependencies should be updated according to the `policy <https://wiki.inkscape.org/wiki/Tracking_Dependencies#Distros>`_ defined in Inkscape wiki .
+
diff --git a/share/extensions/docs/dev/index.rst b/share/extensions/docs/dev/index.rst
new file mode 100644
index 0000000..a38cf03
--- /dev/null
+++ b/share/extensions/docs/dev/index.rst
@@ -0,0 +1,8 @@
+inkex (and core Extensions) development
+=======================================
+
+.. toctree::
+ :maxdepth: 2
+
+ getting-started
+ Writing unit tests <../authors/unit-tests> \ No newline at end of file