Re: font copies in sphinx generated documentation

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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
for example.

On 2/8/22 15:18, Daniel P. Berrangé wrote:
> On Mon, Feb 07, 2022 at 04:51:35PM +0100, Petr Menšík wrote:
>> Hi!
>>
>> 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
>> packages. Not only sphinx packages ships static copies of javascript
>> 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.
>
> Regards,
> Daniel

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
guidelines precisely.

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/
/usr/share/doc/python-sphinx_rtd_theme-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
modified.

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
package.

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
packages. Is FESCO okay with bundled javascript libraries in similar
packages?

Regards,
Petr

-- 
Petr Menšík
Software Engineer
Red Hat, http://www.redhat.com/
email: pemensik@xxxxxxxxxx
PGP: DFCF908DB7C87E8E529925BC4931CA5B6C9FC5CB
_______________________________________________
devel mailing list -- devel@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to devel-leave@xxxxxxxxxxxxxxxxxxxxxxx
Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/
List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
List Archives: https://lists.fedoraproject.org/archives/list/devel@xxxxxxxxxxxxxxxxxxxxxxx
Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure




[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Index of Archives]     [Fedora Announce]     [Fedora Users]     [Fedora Kernel]     [Fedora Testing]     [Fedora Formulas]     [Fedora PHP Devel]     [Kernel Development]     [Fedora Legacy]     [Fedora Maintainers]     [Fedora Desktop]     [PAM]     [Red Hat Development]     [Gimp]     [Yosemite News]

  Powered by Linux