I prefer much more HTML documentation than PDF. While I try to make PDF
also available, HTML is more useful in offline situations, on a train
On 2/8/22 15:18, Daniel P. Berrangé wrote:
> On Mon, Feb 07, 2022 at 04:51:35PM +0100, Petr Menšík wrote:
>> I maintain bind package, which generates html documentation using sphinx
>> and sphinx_rtd_theme. I admit this format is quite popular. Once I have
>> noticed that bind-doc package is quite big. When looking why, I have
>> found not a small number of static copies were generated by
>> documentation process.
>> If I remember correctly, fonts are allowed to be shipped only by font
>> underscore and jquery, but it seems every such package includes also set
>> of fonts contained in its documentation.
> Perhaps I'm mis-interpreting the guidelines, but I don't feel
> like the font packaging rules should apply in this case. When
> we describe the rules for packaging fonts, I feel like that was
> related to fonts that are to be installed for shared usage.
> ie stuff going into /usr/share/fonts should be provided by a
> fonts-xxx package, not as a side effect of some other package.
I admit I thought fonts are allowed to be packaged ONLY in fonts package
and should be reused otherwise. That may not be required.
> The fonts that get copied/around embedded in documentation are
> for private usage by only that documentation. Any shared docs
> generator tools would ideally pull their fonts from common source,
> but whatever they do for output we should just accept. It is not
> a sane use of resources to expect package maintainers to hack the
> generated docs to change how they deal with fonts. Sphinx is just
> one docs tool, there are many other tools, often written just to
> suit the one app in question.
Thanks to Ben Beasley for pointing relevant thread in packaging list, it
revealed the problem is not primary about size wasted by repeated copies
of static content. Especially fonts are included without any hint of
original license. It is non-trivial to obtain original data license and
I am certain most packages ignores it instead of following packaging
I found there are python-sphinx-doc and python-sphinx_rtd_theme-doc,
which are generated by their respective generators.
I compared their contents:
diff -ru /usr/share/doc/python-sphinx-doc/html/_static/
That revealed most of files are not modified template, but exact copy.
Just documentation_options.js and pygments.css seems to be generated and
Could we perhaps create python-sphinx-common package, which would put
common data to /usr/share/doc/python-sphinx-common/_static/ for example.
Then we could make a script for packagers to convert bundled copies to
links. sphinx-package make-shared <path-to-generated-doc-dir>
Such script would remove copies and create relative symlinks to
/usr/share/doc/python-sphinx-common/_static/ content directory. Packager
would then just ensure his doc package Requires: python-sphinx-common
package. Harder work would be done by sphinx packager, which would
ensure common package has all needed Requires: to fonts or js-jquery,
js-underline or similar. He or she would make sure those files stay in
single path and point to minimized or normal from original js library.
Also would ensure they do not depend on python version for example.
Strange thing is, jquery bundled in sphinx package is more recent than
matching js-jquery version in f35. Difference is minimal, but they are
not the same. Opposite situation is with js-underline, which is much
higher version in js-underline than the one bundled in sphinx. Even
original packages do not Provides: bundled(js-jquery) from built doc
If self-contained copy were required, it might not be so hard to prepare
also sphinx-package make-static action, which would dereference symlinks
and replace them with hard link if possible, a file copy otherwise.
sphinx_rtd_theme-package might specialize and extend copied list of
files. It would have its own common subpackage with correct
dependencies. I think such system would allow proper licensing, because
it would point to original package with its well specified license. It
would not work great in case of subdirectories mounted somewhere else.
Script converting shared links to static copies should make it
reasonably simple to create a workaround.
I think that might solve both repeated bundling of JS libraries and
fonts and save visible amount of space. I admit I am not maintainer of
sphinx nor rtd_theme, so most of work would be done outside of my
Red Hat, http://www.redhat.com/
I am having trouble with a build on the ppc64le arch.
I do not have such a machine for testing so that only way I can see to debug it is to try patches in
the spec file that print diagnostic output.
There is no point in running these tests on all the arch values, only the one that is failing.
How do I do this ?