Re: Sphinx/Doxygen HTML documentation and bundling guidelines

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

 



On 28. 09. 21 0:54, Fabio Valentini wrote:
On Mon, Sep 27, 2021 at 3:35 PM Ben Beasley <code@xxxxxxxxxxxxxxxxxx> wrote:

One last follow-up:

It turns out that even the situation with Doxygen is worse. The file
jquery.js inserted by Doxygen was not just a copy of JQuery (js-jquery)
to be unbundled; it also contained in the same file:

- JQuery UI (js-jquery-ui)
- jquery.ScrollTo (https://github.com/flesler/jquery.scrollTo/)
- PowerTip (https://stevenbenner.github.io/jquery-powertip/)
- JQuery UI Touch Punch (js-jquery-ui-touch-punch)
- SmartMenus jQuery Plugin (http://www.smartmenus.org)

It’s possible to account for all of these, package the missing ones
separately, and reconstruct the bundle using unminified sources (or
patch the generated HTML to use separate script tags, yuck), but the
burden is getting ridiculous again. It looks like dropping all
Doxygen-based HTML documentation, or building a less-useful PDF instead,
will be the sensible (but disappointing) outcome.

Thank you for starting this conversation, I had similar thoughts when
I last touched my .spec files for packages that build docs for Python
(with sphinx) or C (with doxygen).

In my opinion, building PDFs instead of HTML docs would actually be an
improvement in at least some ways:
There's no weird bundled JavaScript libraries, and docs can get
shipped as a single file (?) instead of lots and lots of small HTML /
JS / CSS files (with questionable licenses).

PDF is probably as "standard file format" today as HTML (even most web
browsers can open them), and probably all Fedora Editions and Spins
ship with a PDF viewer anyway (most of which also have good Ctrl-F and
PDF chapter bookmark functionality, which is way nicer than clicking
through dozens of hyperlinks in HTML docs).

At any rate, discoverability of pre-built docs from Fedora packages is
very poor to start with:
- most are hidden away in a separate -doc subpackage that doesn't get
installed by default
- even if the package is installed, the user has to manually navigate
their file browser to /usr/share/doc/foo/html/ (or similar), then open
the "index.html" file, and hopefully not forget to add a browser
bookmark for it

So, I'm not sure if the benefits of building HTML (or PDF, for that
matter) docs actually outweighs the headache they often cause.


For Sphinx HTML at least, a "proper" solution might be to create (and maintain) a Public Domain theme that does not bundle any JavaScript etc. and uses shared resources from Fedora if needed (or better yet, does not use any), and ask packagers to manually change the theme to this one. If that works, we could even provide a convenient macro/script to build it instead of requiring each package to patch conf.py.

As for PDF docs, has anybody checked if they bundle fonts?

--
Miro Hrončok
--
Phone: +420777974800
IRC: mhroncok
_______________________________________________
packaging mailing list -- packaging@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to packaging-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/packaging@xxxxxxxxxxxxxxxxxxxxxxx
Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure




[Index of Archives]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite Forum]     [KDE Users]

  Powered by Linux