From 2eb6c90d395bf8b1391dc423ed36d701385fa0fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcus=20Sch=C3=A4fer?= Date: Fri, 2 Feb 2024 10:27:31 +0100 Subject: [PATCH] Drop PDF build of the documentation The kiwi.pdf file as provided in the kiwi-man-pages package was never really used by our users but comes with a huge dependency chain to LaTex. We provide the documentation online as well as converted to DocBook from where all other formats could be derived. Thus there is no need for us to produce an extra PDF document which is imho never consulted. Along with this change there is also a new meta package called kiwi-devel which should make it easier for people to pull in packages for kiwi development. This was formerly done by the helper/install_devel_packages script which was pretty much outdated. I expect there is more attention on the package than on a custom script in some helper directory. Having a kiwi-devel also simplifies the contribution chapter which was not really user friendly regarding the needed development dependencies --- MANIFEST.in | 1 - Makefile | 9 ---- doc/source/contributing.rst | 83 ++++++------------------------- helper/install_devel_packages.sh | 31 ------------ package/python-kiwi-spec-template | 23 ++++++++- tox.ini | 10 ---- 6 files changed, 36 insertions(+), 121 deletions(-) delete mode 100755 helper/install_devel_packages.sh diff --git a/MANIFEST.in b/MANIFEST.in index 02b559a7886..3ab1e1037aa 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -37,7 +37,6 @@ include tox.ini include kiwi.yml recursive-include doc/build/man * -recursive-include *.gz *.iso *.kiwi *.pf2 *.py *.txt *.xml *.xz include .bumpversion.cfg include .coverage* diff --git a/Makefile b/Makefile index 35e50915199..eeac072c095 100644 --- a/Makefile +++ b/Makefile @@ -25,8 +25,6 @@ install_dracut: install_package_docs: install -d -m 755 ${buildroot}${docdir}/python-kiwi - install -m 644 doc/build/latex/kiwi.pdf \ - ${buildroot}${docdir}/python-kiwi/kiwi.pdf install -m 644 LICENSE \ ${buildroot}${docdir}/python-kiwi/LICENSE install -m 644 README.rst \ @@ -109,13 +107,6 @@ build: clean tox mv setup.pye setup.py # provide rpm source tarball mv dist/kiwi-${version}.tar.gz dist/python-kiwi.tar.gz - # append PDF documentation to tarball - gzip -d dist/python-kiwi.tar.gz - mkdir -p kiwi-${version}/doc/build/latex - mv doc/build/latex/kiwi.pdf kiwi-${version}/doc/build/latex - tar -uf dist/python-kiwi.tar kiwi-${version}/doc/build/latex/kiwi.pdf - gzip dist/python-kiwi.tar - rm -rf kiwi-${version} # update rpm changelog using reference file helper/update_changelog.py --since package/python-kiwi.changes > \ dist/python-kiwi.changes diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index ed544211b03..66aa66db945 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -44,53 +44,19 @@ Create a local clone of the forked repository Install Required Operating System Packages ------------------------------------------ -{kiwi} requires the following additional packages which are not provided by -:command:`pip`. Those will be installed by calling the -`install_devel_packages.sh` helper script from the checked out Git -repository as follows: +{kiwi} requires additional packages for development which are not +provided by :command:`pip`. Those will be pulled in by installing +the following development packages: -.. code:: shell-session - - $ sudo helper/install_devel_packages.sh - -.. note:: - - The helper script checks for the package managers `zypper` and - `dnf` and associates a distribution with it. If you use a - distribution that does not use one of those package managers - the script will not install any packages and exit with an - error message. In this case we recommend to take a look at - the package list encoded in the script and adapt to your - distribution and package manager as needed. Because distributions - also changes on a regular basis it might happen that the - `install_devel_packages` helper is not 100% accurate or outdated - depending on your host system. In this case the following - list describes the needed components and we are happy to - received feedback or patches to make `install_devel_packages` - a better experience. - -XML processing libraries - `libxml2` and `libxslt` (for :mod:`lxml`) - -Python header files, GCC compiler and glibc-devel header files - Required for python modules that hooks into shared library context - and often named similar to: `python3-devel` - -Spell Checking library - Provided by the `enchant` library - -ShellCheck - `ShellCheck `_ script linter. - -ISO creation program `xorriso`. +* kiwi-develdeps +* kiwi-systemdeps -LaTeX documentation build environment - A full LaTeX installation is required to build the PDF documentation - [#f1]_. - -Host Requirements To Build Images - A set of tools needed to build images and provided by - the `kiwi-systemdeps` package +The packages are provided on the Open Build Service in the +`Virtualization:Appliances:Builder +`__ +project. For manual inspection of the development packages +that are pulled in please refer to the `package/python-kiwi-spec-template` +spec file from the checked out Git repository. Create a Python Virtual Development Environment ----------------------------------------------- @@ -255,27 +221,16 @@ Coding Style - The names of constants are not written in all capital letters. - Documentation ~~~~~~~~~~~~~ -{kiwi} uses `Sphinx `_ for the API and -user documentation. - -In order to build the HTML documentation call: +{kiwi} uses `Sphinx `_ for the API, +user documentation and manual pages .. code:: shell-session tox -e doc -or to build the full documentation (including a PDF generated by LaTeX -[#f3]_): - -.. code:: shell-session - - tox -e packagedoc - - Document all your classes, methods, their parameters and their types using the standard `reStructuredText `_ @@ -326,7 +281,7 @@ found in `doc/source`. General documentation should be put into the specialized topics would belong into the `building/` subfolder. Adhere to a line limit of 75 characters when writing the user facing -documentation [#f2]_. +documentation [#f1]_. Additional Information @@ -432,13 +387,7 @@ directly build it with :command:`rpmbuild`, :command:`fedpkg`, or submitted to the Open Build Service using :command:`osc`. -.. [#f1] Sphinx requires a plethora of additional LaTeX - packages. Unfortunately there is currently no comprehensive list - available. On Ubuntu/Debian installing `texlive-latex-extra` - should be sufficient. For Fedora, consult the package list - from :file:`.gitlab-ci.yml`. - -.. [#f2] Configure your editor to automatically break lines and/or reformat +.. [#f1] Configure your editor to automatically break lines and/or reformat paragraphs. For Emacs you can use `M-x set-fill-column RET 75` and `M-x auto-fill-mode RET` for automatic filling of paragraphs in conjunction with `M-x fill-paragraph` (usually bound to `M-q`) to @@ -447,5 +396,3 @@ to the Open Build Service using :command:`osc`. Emacs since version `23.1`). Vim users can set the text width via `:tw 75` and then use the commands `gwip` or `gq`. - -.. [#f3] Requires a full LaTeX installation. diff --git a/helper/install_devel_packages.sh b/helper/install_devel_packages.sh deleted file mode 100755 index e6b15143a42..00000000000 --- a/helper/install_devel_packages.sh +++ /dev/null @@ -1,31 +0,0 @@ -#!/bin/bash - -source /etc/os-release - -case ${ID} in - fedora|centos|rhel) - dnf --setopt=install_weak_deps=False install \ - python3 python3-devel 'python3dist(pip)' \ - 'python3dist(tox)' make gcc which xz xorriso libxml2-devel \ - libxslt-devel enchant enchant-devel genisoimage ShellCheck \ - latexmk texlive-cmap texlive-metafont texlive-ec libffi-devel \ - texlive-babel-english texlive-fncychap texlive-fancyhdr \ - texlive-titlesec texlive-tabulary texlive-framed texlive-wrapfig \ - texlive-parskip texlive-upquote texlive-capt-of texlive-needspace \ - texlive-makeindex texlive-times texlive-helvetic texlive-courier \ - texlive-gsftopk texlive-dvips trang kiwi-systemdeps - ;; - opensuse-*|sles) - zypper install --no-recommends \ - python3-devel python3-tox libxml2-devel libxslt-devel glibc-devel \ - gcc xorriso texlive-fncychap texlive-wrapfig texlive-capt-of \ - texlive-latexmk texlive-cmap texlive-babel-english \ - texlive-times texlive-titlesec texlive-tabulary texlive-framed \ - texlive-float texlive-upquote texlive-parskip texlive-needspace \ - texlive-makeindex-bin texlive-collection-fontsrecommended \ - texlive-psnfss libffi-devel enchant-devel trang kiwi-systemdeps - ;; - *) - echo "Unknown distribution: ${os}" - ;; -esac diff --git a/package/python-kiwi-spec-template b/package/python-kiwi-spec-template index 0ab96c5a176..0a8d2c5b006 100644 --- a/package/python-kiwi-spec-template +++ b/package/python-kiwi-spec-template @@ -75,6 +75,23 @@ The KIWI Image System provides an operating system image builder for Linux supported hardware platforms as well as for virtualization and cloud systems like Xen, KVM, VMware, EC2 and more. +%package -n kiwi-develdeps +Summary: KIWI - Development dependencies +Group: %{sysgroup} +Requires: gcc +Requires: glibc-devel +Requires: libffi-devel +Requires: trang +Requires: libxml2-devel +Requires: libxslt-devel +Requires: python%{python3_pkgversion}-tox +Requires: python%{python3_pkgversion}-%{develsuffix} >= 3.6 +Requires: python%{python3_pkgversion}-setuptools + +%description -n kiwi-develdeps +This metapackage installs the necessary dependencies +to develop KIWI. + %package -n kiwi-systemdeps-core Summary: KIWI - Core host system dependencies Group: %{sysgroup} @@ -632,7 +649,7 @@ make buildroot=%{buildroot}/ install # Install dracut modules make buildroot=%{buildroot}/ install_dracut -# Install documentation in PDF format +# Install documentation README / LICENSE make buildroot=%{buildroot}/ docdir=%{_defaultdocdir}/ install_package_docs # Create symlinks for correct binaries @@ -668,6 +685,9 @@ fi %endif %endif +%files -n kiwi-develdeps +# Empty metapackage + %files -n kiwi-systemdeps-core # Empty metapackage @@ -708,7 +728,6 @@ fi %{_defaultdocdir}/python-kiwi/README %files -n kiwi-man-pages -%{_defaultdocdir}/python-kiwi/kiwi.pdf %config %_sysconfdir/kiwi.yml %doc %{_mandir}/man8/* diff --git a/tox.ini b/tox.ini index de484c0b1d1..3fbd704b7cd 100644 --- a/tox.ini +++ b/tox.ini @@ -138,7 +138,6 @@ usedevelop = True deps = {[testenv]deps} changedir=doc commands = - {[testenv:doc.latexpdf]commands} {[testenv:doc.man]commands} @@ -188,15 +187,6 @@ commands = mv build/xml build/restxml -[testenv:doc.latexpdf] -description = Documentation build PDF result -skip_install = True -deps = {[testenv:doc]deps} -changedir=doc -commands = - make latexpdf - - [testenv:doc.man] description = Documentation build man pages skip_install = True