https://bugzilla.redhat.com/show_bug.cgi?id=2369464 --- Comment #7 from Benson Muite <benson_muite@xxxxxxxxxxxxx> --- (In reply to Ben Beasley from comment #6) > (In reply to Benson Muite from comment #5) > > > > For Sphinx, it is possible to add macros to make this easier, as new > > macros are being added, it is a good time to consider this and make > > people aware it is available. > > > > […] > > > > Docbook does not introduce extra fonts, js or CSS and there is a viewer > > already packaged. There is some expertise in Fedora for docbook format: > > https://packages.fedoraproject.org/pkgs/publican/ > > Indeed, Docbook looks like it has potential for this kind of documentation, > and I am interested in the idea of a better way to deal with > Sphinx-generated documentation in general. I just don’t see a reason for > this particular package to be in the vanguard of that. > > I’m not saying it’s a bad format. It does seem to avoid a lot of the > pitfalls of some other formats, which is kind of exciting, although I > haven’t reviewed the result in a viewer to see how well it actually turned > out. I’m just not sure that introducing Sphinx-generated docbook files to a > handful of individual packages does much good except as a proof of concept. > > It seems like, for the effort of building this kind of documentation to be > worthwhile, we need at least a partial consensus that (1) “we collectively > value packaging generated Python library API documentation,” (2) > “Sphinx-generated docbook output is normally of good quality in practice,” > and (3) “this is how we would like to present Python library API > documentation by default,“ especially for a format that many people, even > developers, aren’t used to dealing with. If that consensus existed, I could > quickly add docbook documentation to *dozens* of packages, even only > considering those for which I am primary maintainer, but I am not yet > confident that adding and maintaining this format is a good use of time and > other resources. Rendering in yelp is good and consistent. The only issue for the current package is latex is not correctly converted, but this is an upstream problem. The format is stable, and there is already significant functional tooling. The only factor complicating building this documentation is that the sometimes needs to already be available, requiring either modifying PYTHON_PATH or using a bootstrap build. As docbook can be produced from texinfo files, not only sphinx, but other documentation generators such as doxygen can also be used. Last build at https://copr.fedorainfracloud.org/coprs/fed500/python-pyscipopt/builds/ includes images. It is not a blocking requirement to include it, but maybe worth viewing the documentation to give an opinion. -- 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=2369464 Report this comment as SPAM: https://bugzilla.redhat.com/enter_bug.cgi?product=Bugzilla&format=report-spam&short_desc=Report%20of%20Bug%202369464%23c7 -- _______________________________________________ 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, report it: https://pagure.io/fedora-infrastructure/new_issue
