Script 'mail_helper' called by obssrc Hello community, here is the log from the commit of package kapidox for openSUSE:Factory checked in at 2022-08-15 19:58:04 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Comparing /work/SRC/openSUSE:Factory/kapidox (Old) and /work/SRC/openSUSE:Factory/.kapidox.new.1521 (New) ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Package is "kapidox" Mon Aug 15 19:58:04 2022 rev:105 rq:994949 version:5.97.0 Changes: -------- --- /work/SRC/openSUSE:Factory/kapidox/kapidox.changes 2022-07-10 23:15:42.104982940 +0200 +++ /work/SRC/openSUSE:Factory/.kapidox.new.1521/kapidox.changes 2022-08-15 20:00:11.037388641 +0200 @@ -1,0 +2,12 @@ +Sun Aug 7 22:27:10 UTC 2022 - Christophe Giboudeaux <christo...@krop.fr> + +- Update to 5.97.0 + * New feature release + * For more details please see: + * https://kde.org/announcements/frameworks/5/5.97.0 +- Changes since 5.96.0: + * Improve getting started docs +- Add patch to fix installation: + * 0001-Fix-broken-installation.patch + +------------------------------------------------------------------- Old: ---- kapidox-5.96.0.tar.xz kapidox-5.96.0.tar.xz.sig New: ---- 0001-Fix-broken-installation.patch kapidox-5.97.0.tar.xz kapidox-5.97.0.tar.xz.sig ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Other differences: ------------------ ++++++ kapidox.spec ++++++ --- /var/tmp/diff_new_pack.KiIBJz/_old 2022-08-15 20:00:11.525390002 +0200 +++ /var/tmp/diff_new_pack.KiIBJz/_new 2022-08-15 20:00:11.529390013 +0200 @@ -18,13 +18,13 @@ # Only needed for the package signature condition %bcond_without released -%define _tar_path 5.96 +%define _tar_path 5.97 # Full KF5 version (e.g. 5.33.0) %{!?_kf5_version: %global _kf5_version %{version}} # Last major and minor KF5 version (e.g. 5.33) %{!?_kf5_bugfix_version: %define _kf5_bugfix_version %(echo %{_kf5_version} | awk -F. '{print $1"."$2}')} Name: kapidox -Version: 5.96.0 +Version: 5.97.0 Release: 0 Summary: Scripts and data for building API documentation License: BSD-2-Clause @@ -35,6 +35,8 @@ Source1: %{name}-%{version}.tar.xz.sig Source2: frameworks.keyring %endif +# PATCH-FIX-UPSTREAM +Patch0: 0001-Fix-broken-installation.patch BuildRequires: fdupes BuildRequires: kf5-filesystem BuildRequires: python-rpm-macros @@ -61,7 +63,7 @@ %install python3 setup.py install --prefix=%{_kf5_prefix} --root=%{buildroot} -%fdupes %{buildroot} +%fdupes -s %{buildroot} %files %license LICENSES/* ++++++ 0001-Fix-broken-installation.patch ++++++ >From 768ece9056721315b8d0a237dc603e2ce7830303 Mon Sep 17 00:00:00 2001 From: Christophe Giboudeaux <christo...@krop.fr> Date: Wed, 10 Aug 2022 07:54:39 +0200 Subject: [PATCH] Fix broken installation Patch picked from Debian. Fixes: https://invent.kde.org/frameworks/kapidox/-/issues/14 --- MANIFEST.in | 1 + setup.py | 1 + 2 files changed, 2 insertions(+) create mode 100644 MANIFEST.in diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..c38095f --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1 @@ +recursive-include kapidox/data * diff --git a/setup.py b/setup.py index 12b1d07..0409aa1 100755 --- a/setup.py +++ b/setup.py @@ -8,6 +8,7 @@ setup( maintainer_email='oliv...@churlaud.com', url='https://invent.kde.org/frameworks/kapidox', packages=find_packages(), + include_package_data=True, python_requires=">=3.8", scripts=['kapidox/depdiagram_generate_all'], entry_points={ -- 2.37.1 ++++++ kapidox-5.96.0.tar.xz -> kapidox-5.97.0.tar.xz ++++++ diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/kapidox-5.96.0/README.md new/kapidox-5.97.0/README.md --- old/kapidox-5.96.0/README.md 2022-06-12 21:37:54.000000000 +0200 +++ new/kapidox-5.97.0/README.md 2022-07-22 04:17:55.000000000 +0200 @@ -4,7 +4,8 @@ This framework contains scripts and data for building API documentation (dox) in a standard format and style. -https://api.kde.org holds the result. + +https://api.kde.org holds the result, and this very page is handled by KApiDox too: https://api.kde.org/frameworks/kapidox/html/index.html. The [Doxygen](https://www.doxygen.nl) tool performs the actual documentation extraction and formatting. This framework provides a wrapper script to make generating the @@ -12,41 +13,110 @@ framework or other module) and a standard template for the generated documentation. - -## Dependencies - ## Installation -Python 3 is required to run the scripts. Additionally you -need to have the jinja2 and yaml (or pyyaml) modules. +Python 3 is required to run the scripts, as well as the `jinja`, `pyyaml`, `requests`, `doxypypy` and `doxyqml` python modules. -The following command creates a venv and installs the tool: +The following command creates a venv and installs the tool alongside all its modules: - $ ./bootstrap-devenv.sh - -### Optional -Doxyqml and doxypypy might be needed to let doxygen document qml -and python sources respectively. +``` +bash ./bootstrap-devenv.sh +``` To generate the dependency diagrams, you need the Graphviz Python bindings. They are currently not available from pip, but most distributions provide them. You can get binaries and source archives from <https://www.graphviz.org/download/>. -## Usage +## Workflow + +This document describes two ways to use KApiDox to generate documentation for KDE software: the manual way, and the container way. Both can apply to standalone repositories or to projects built using [kdesrc-build](https://community.kde.org/Get_Involved/development#Set_up_kdesrc-build), but the main role of the manual method is mostly to learn how the tool works, whereas the container method should be the cleaner, more convenient way. + +### The manual way + +With this method, we will be using three directories (kirigami, kapidox and kirigamidocs). + +First, clone the desired repository as well as the KApiDox repository. In this example we will use Kirigami: + +```bash +git clone https://invent.kde.org/frameworks/kirigami.git +git clone https://invent.kde.org/frameworks/kapidox.git +``` + +You may use the ssh:// version instead if you have a developer account. + +You should now have a `kirigami` and a `kapidox` folder. Make a new folder to store the local test HTML documentation, then switch to the kapidox directory: + +```bash +mkdir kirigamidocs +cd kapidox +``` + +Run the script provided by the KApiDox repository. This only needs to be done once, and it will download and install the needed Python3 modules and generate a proper Python virtual environment: + +```bash +bash bootstrap-devenv.sh +``` + +After the script is done, you should have a hidden folder called `.kapidox_venv/`, inside of which is a `bin/` folder containing the files we will be using. If the shell you are using is bash or zsh, you can run `./activate` to activate the Python virtual venv. If you are using csh or fish, you may use `./activate.csh` or `./activate.fish`, respectively. + +After activating the Python venv, your terminal prompt should change to that of a venv. Switch to the folder we created earlier and run kapidox-generate by pointing to the folder containing the target project repository (in this case, Kirigami): + +```bash +cd ../kirigamidocs +kapidox-generate ../kirigami +``` -Although it should be possible to use kapidox directly it is recommended to run the tool in the docker container. +It can take a while. After it is done, for convenience, do not close this venv shell yet. -You can build the docker image like this: +You should have an `index.html` file which should be the entrypoint of the new documentation. You can open a new instance of your terminal or another tab, then open it directly from your terminal by using `xdg-open index.html` or `kioclient exec index.html`, or whichever other method you'd like. + +After that, you may edit the Doxygen-formatted documentation in *.qml or *.h files using Kate or your favorite editor. + +After you're finished editing, you can switch back to the venv in the `kirigamidocs/` folder, check that you are in the correct folder with `pwd`, and run the following to regenerate the locally edited documentation: + +```bash +pwd // outputs ~/kirigamidocs +rm -rf * && kapidox-generate ../kirigami +``` + +Now that you understand how to generate the venv and how to use `kapidox-generate`, you can easily apply this knowledge to projects built using kdesrc-build. Assuming you're using bash: + +```bash +kdesrc-build kapidox +// ...building... +kdesrc-build kirigami +// ...building... +mkdir ~/kirigamidocs +cd ~/kde/src/kapidox +bash bootstrap-devenv.sh +source .kapidox_venv/bin/activate +cd ~/kirigamidocs +kapidox-generate ~/kde/src/kirigami +// ...edit files... +rm -rf * && kapidox-generate ~/kde/src/kirigami +``` + +### The container way + +Although it is possible to use KApiDox directly, using it in a container can be much more convenient once it is set up. + +You can build a new image with docker or podman: + +```bash +docker build . -t kapidox_generate:latest +// OR +podman build . -t kapidox_generate:latest +``` - docker build . -t kapidox_generate:latest +By running `docker images` or `podman images` you should now see an image called `localhost/kapidox_generate`. To run `kapidox-generate` with a project that you want to generate the docs from you need an empty folder for the results (`/path/to/build/folder`). The build directory inside the container is set as `BUILD_DIR` in `Dockerfile`, and must stay in sync with what is used as `CONTAINER_BUILD_DIR` in the volume mapping. For this example we use `libksane` checked out to `/path/to/libksane`: ```bash -export HOST_PROJECT_SRC=/path/to/libksane -export HOST_BUILD_DIR=/path/to/build/folder +export HOST_PROJECT_SRC=/path/to/libksane/folder +export HOST_BUILD_DIR=/path/to/libksane/build/folder export CONTAINER_PROJECT_SRC=/home/kapidox/libksane export CONTAINER_BUILD_DIR=/home/kapidox/apidox-build mkdir $HOST_BUILD_DIR @@ -72,8 +142,7 @@ run on: ### README.md -Most importantly, there should be a `README.md` file, like this page (backward -compatibility also authorize `Mainpage.dox` files). The first line of this file +Most importantly, there should be a `README.md` file that works as the main page, like one where this documentation is written in (backward compatibility also authorize `Mainpage.dox` files). The first line of this file is particularly important, as it will be used as the title of the documentation. ### metainfo.yaml @@ -97,10 +166,10 @@ By default, the source of the public library must be in `src`, if the documentation refers to any dot files, these should be in `docs/dot`. Images should be in `docs/pics`, and snippets of example code should be in -`examples`. See the doxygen documentation for help on how to refer to these +`examples`. See the [Doxygen documentation](https://doxygen.nl/manual/index.html) for help on how to refer to these files from the dox comments in the source files. -If you need to override any doxygen settings, put them in a `docs/Doxyfile.local` in your project. +If you need to override any Doxygen settings, put them in a `docs/Doxyfile.local` in your project. Global settings are defined in `src/kapidox/data/Doxyfile.global`. ## Generating the documentation diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/kapidox-5.96.0/setup.py new/kapidox-5.97.0/setup.py --- old/kapidox-5.96.0/setup.py 2022-06-12 21:37:54.000000000 +0200 +++ new/kapidox-5.97.0/setup.py 2022-07-22 04:17:55.000000000 +0200 @@ -2,7 +2,7 @@ setup( name='kapidox', - version='5.96.0', + version='5.97.0', description='KDE API documentation generation tools', maintainer='Olivier Churlaud', maintainer_email='oliv...@churlaud.com',
