Skip to content

Various documentation improvements

What does the merge request do?

Pull information from wiki.inkscape.org and the Gitlab Project wiki

Documentation was scattered around. The advantage of having it in one place is obvious, and when having it in the Sphinx doc, we can easily link from the python files to the documentation and vice versa.

For the documentation of the inx widgets, I recreated the images and removed the 1.0-deprecations, they don't work anymore.

For the tutorials in the project Wiki, I separated the two tutorials that were incorrectly combined in "My first effect extension" - we now have one for "Make all selected objects red" and "Color path based on node parity". The tutorial quality was improved, links to the API doc added where sensible, and sample solution files added.

(Side note: Why should a tutorial ever contain such a sentence?)

You may get a popup about a deprecation warning, but all is well

Added additional documentation

By popular request in the chat, there is now documentation for developing inkex, as well as a contributing.md file pointing to that documentation.

Add versioning info

I went through the diffs of Inkex 1.0 -> 1.1 and 1.1 -> 1.2 to document what changed in Inkex in the specific major versions. This looks like this: https://joneuhauser.gitlab.io/-/extensions/-/jobs/2135084770/artifacts/build/html/source/inkex.utils.html

Sphinx can even generate changelogs that only include these remarks, but not sure if we need that.

This MR also upgrades the Sphinx generation mechanism since the route via setup.py is deprecated (https://www.sphinx-doc.org/en/master/usage/advanced/setuptools.html)

Implementation notes

  • This merge request contains fixes to docstrings / better descriptions where I noticed a need for that.
  • I updated the deprecated decorator. If a version string is passed as argument, the docstring is changed such that the Sphinx directive is correctly created. Also this allows us to better track when we can remove something for good.
  • The deprecated method width and height of SvgDocumentElement was monkey-patched into BaseElement - probably to avoid circular dependency issues (importing this class into deprecated/main.py fails). That is too broad, since there are legitimate width and height methods in subclasses (e.g. page) - if they have no docstring themselves, they also show the "deprecation" method in the documentation. I moved the deprecation code to _svg.py.
  • The methods and classes are now listed in the order of implementation and not alphabetically. We can override sorting with the __all__ variable in a module, but that's a nightmare to maintain (needs to be updated every time a new method is added). I'm open for suggestions here.
  • Changed documentation theme to pydata-sphinx-theme, this is better suited for documentation projects with different target groups.

Summary for release notes

(in documentation section)

  • All the documentation from the Wiki and the Gitlab project wiki has been compiled in a single place.
  • The tutorials for extension authors have been improved.
  • Versioning information is now contained in the documentation. This shows extensions authors in which Inkscape version new API functionality was added or deprecated.

Checklist

  • Add unit tests (if applicable)
  • Changes to inkex/ are well documented. In the future this also contains the sphinx directives!
  • Clean merge request history
Edited by Jonathan Neuhauser

Merge request reports