https://bugzilla.redhat.com/show_bug.cgi?id=2006555 --- Comment #4 from Ben Beasley <code@xxxxxxxxxxxxxxxxxx> --- I just followed up on the packaging mailing list with: ----- I’ve used cairomm as a case study for trying to bring a Doxyen-based HTML documentation package into compliance, and python-autodocsumm as a case study for Sphinx. ----- For cairomm, I have unbundled js-jquery and altered the License for the -doc subpackage. I am not treating the Doxygen-generated JavaScript files as bundled libraries because they are templated and project-dependent, not simply copied in as fully-reusable libraries. While Doxygen does not insert a standalone license file for its MIT license, the text is at least present in the JavaScript file headers. I might have missed mentioning some non-JavaScript files inserted by Doxygen that are potentially MIT-licensed but do not reference their license. Another solution would be to ask Doxygen to build a PDF instead of HTML. The result would have no visible bundled assets, but in my opinion would be less convenient for users. There are some judgement calls here, but I think the result (https://src.fedoraproject.org/rpms/cairomm/c/948e04f946d95612948d81d9090e2bcfa95abe56?branch=rawhide) is reasonable. ----- The situation for python-autodocsumm’s Sphinx documentation is more dire. I can unbundle the Sphinx-inserted copies of js-jquery and js-underscore. I can add virtual Provides for Sphinx’s libraries doctools.js and searchtools.js: Provides: bundled(js-sphinx-doctools) Provides: bundled(js-sphinx-searchtools) although I cannot version them, because the version could only be that of Sphinx itself, and that changes regularly without alterations to my package’s sources; I don’t know a way to handle that automatically, and I could not reasonably keep it synchronized manually. These libraries were never intended to be handled separately from the documentation they support. I can claim that language_data.js and documentation_options.js are not bundled libraries, because they are generated from templates using project-dependent options. Now I have the problem that all of the Sphinx-inserted files in _static have the same BSD license as Sphinx itself, but they only reference the Sphinx LICENSE file in their headers; they do not contain license text at all, and BSD is one of the licenses where license text is required. I could possibly handle this by copying in the license file from the Sphinx package in the build environment. I’d better make sure I don’t miss a hypothetical Sphinx license change, so I should probably grep that license file in %check for a key phrase to make sure its contents are what I expect. Now I’m left with the theme. The autodocsumm documentation uses sphinx_rtd_theme, which is a very common choice. Theme files are mostly in _static/css/ and _static/js/. In _static/js/, there are two JavaScript files, badge_only.js and theme.js. Both are minified and contain no license information. Okay, I can check the license of python3-sphinx_rtd_theme, and maybe I can copy in the unminified versions manually to comply with that part of the guidelines. Oh, it turns out only the minified versions are packaged, so there’s nothing I can do. (Well—shipping only minified files isn’t compliant with guidelines, so I could send a PR or file an issue on python-sphinx_rtd_theme and expect the maintainer to do something about it. I’m not trying to call out this particular package or its maintainers, as it’s very hard to find and deal with all the bits of JavaScript and web content that are tucked away in Python packages these days, and such oversights are rampant in existing packages.) In _static/css/, there are two corresponding CSS files, badge_only.css and theme.css. Both have the same problems (minified only, no license information), but *also*, theme.css has a bundled copy of the CSS from Font Awesome 4.7.0. That’s also MIT-licensed, with only a URL for the license and no included license text. ----- This is the point at which I say that the burden of trying to package this near-minimal example of Sphinx-generated documentation in strict compliance with the guidelines is unreasonable, and I drop it, along with the documentation in all other Python packages for which I am responsible. I would be surprised if there is even one case where HTML documentation for a Python package is currently packaged in a way that truly satisfies all of these requirements around license text, web assets, JavaScript, and bundling; and I suspect the broader situation for Doxygen and other documentation generators is not much better. As a user who has often needed to work offline for various reasons, it would be a great loss if the solution really has to be that HTML documentation should not be packaged in general. -- 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
