[Bug 2006555] Review Request: python-autodocsumm - Extending your autodoc API docs with a summary

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

 



https://bugzilla.redhat.com/show_bug.cgi?id=2006555



--- Comment #3 from Ben Beasley <code@xxxxxxxxxxxxxxxxxx> ---
For future reference, a copy of my posting to the packaging mailing list
(linked above) follows:

-----


It was recently brought up in a package review
(https://bugzilla.redhat.com/show_bug.cgi?id=2006555) that a Sphinx-generated
HTML documentation package contained several JavaScript libraries, and that:

  1. their licenses should be accounted for and added to the License
     field for the -doc subpackage
  2. they should be treated as bundled libraries and marked with virtual
     Provides

Note that the JavaScript is inserted by the Sphinx documentation build system,
and is not present in the source tarball. Your “typical” Sphinx documentation
has minified and unminified copies of JQuery (js-jquery) and Underscore
(js-underscore), both MIT-licensed, plus several unminified utility libraries
that belong to Sphinx itself (doctools.js, language_data.js, searchtools.js).
The overall Sphinx project is BSD-licensed. The details vary by theme, but this
is the most common case.

To me, it seems that this feedback is a reasonable strict reading of the
relevant packaging guidelines. If this is the right interpretation of Fedora
policy, what should be done about it in general?

-----

Based on looking for installed files named “searchtools.js” in packages named
-doc or -docs, there are about 600 documentation packages generated with
Sphinx. This might miss some that have exotic themes.

As far as I can tell, only one existing package in the distribution,
python-murano-package-check, tries to use virtual Provides to track the
libraries that belong to Sphinx itself:

  Provides:       bundled(js-doctools)
  Provides:       bundled(js-jquery) = 3.1.0
  Provides:       bundled(js-searchtools)
  Provides:       bundled(js-underscore) = 1.3.1
  Provides:       bundled(js-websupport)

and this package does not actually build its documentation subpackage.

Only the following packages have virtual Provides for js-jquery and
js-underscore. In most cases these lack the version numbers.

  - arb-doc
  - mpdecimal-doc
  - python-BTrees-doc
  - python-latexcodec-doc
  - python-networkx-doc
  - python3-persistent-doc
  - sympy-doc

Of the packages in the list above, only mpdecimal-doc has a License field that
seems to try to account for the licenses of the JavaScript libraries.

-----

Personally, I can add virtual Provides and adjust the License on the -doc
subpackage for my package under review, and it’s even possible for me to
replace the Underscore and JQuery libraries with symbolic links to those
installed by js-jquery and js-underscore. However, changing one package, or
even every package I control, is a tiny drop in a vast ocean of documentation
packages. Consider, for example, that Doxygen also includes JQuery and several
Doxygen-specific libraries in its output, so the same arguments about licenses
and virtual Provides apply to it. A search for “dynsections.js” in packages
named *-doc or *-docs gives nearly 400 Doxygen-based packages.

If this is a real problem, it seems like it needs to be handled and/or
documented in a way that can potentially scale to the rest of those 600
Sphinx-based packages, to the nearly 400 Doxygen-based packages, and beyond
that to the output of other documentation systems. I am not sure what that
would look like.

All thoughts are welcome.


-- 
You are receiving this mail because:
You are on the CC list for the bug.
You are always notified about changes to this product and component
https://bugzilla.redhat.com/show_bug.cgi?id=2006555
_______________________________________________
package-review mailing list -- package-review@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to package-review-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/package-review@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]     [Yosemite Conditions]     [KDE Users]

  Powered by Linux