Re: [libvirt] [PATCH] docs: remove devhelp API docs
On Thu, 2019-09-05 at 13:34 +0100, Daniel P. Berrangé wrote: > We currently generate two completely separate API references for the > libvirt public API. One at 'docs/html/' and one at 'docs/devhelp/'. > Both are published on the website, but we only link to content in > the 'docs/html/' pages. > > Both are installed in the libvirt-docs sub-RPM, with a full copy > of the website including 'docs/html/' in /usr/share/docs/libvirt-docs, > while the 'docs/devhelp/' content goes to /usr/share/gtk-doc/. The > latter was broken for years until: > > commit ca6f602546cb28658db05f29bc840e04d22d0947 > Author: Andrea Bolognani > Date: Fri May 10 14:54:52 2019 +0200 > > docs: Introduce $(devhelphtml_generated) > > Our XSLT magic generates one Devhelp-compatible HTML file > per documentation module, but so far we have only shipped > and installed documentation for virterror. > > Now that we have $(modules), however, we can generate the > list of files the same way we do for regular documentation > and make sure we always ship and install everything. > > That this bug went unnoticed for so long is a sign of how few > people are using the devhelp docs. The only commits to the devhelp > code since it was first introduced have been fixing various build > problems that hit. > > The only obvious difference between the two sets of docs is the CSS > styling in use. Overall devhelp does not look compelling enough to > justify having two duplicated sets of API docs. Eliminating it will > reduce the amount of XSL code we are carrying in the tree which is > an attractive benefit. > > Signed-off-by: Daniel P. Berrangé > --- > docs/Makefile.am | 38 +-- > docs/devhelp/devhelp.xsl | 131 - > docs/devhelp/home.png| Bin 654 -> 0 bytes > docs/devhelp/html.xsl| 573 --- > docs/devhelp/left.png| Bin 459 -> 0 bytes > docs/devhelp/right.png | Bin 472 -> 0 bytes > docs/devhelp/style.css | 66 - > docs/devhelp/up.png | Bin 406 -> 0 bytes > libvirt.spec.in | 8 - > 9 files changed, 1 insertion(+), 815 deletions(-) As the person who spent time fixing Devhelp support a while ago, I'm perfectly fine dropping it. Perhaps I should have gone this route myself in the first place :) I don't have time to look at the patch in detail, but from a quick look I didn't spot any obvious issues, plus if there were any I trust Pavel would have found them during his review, so Reviewed-by: Andrea Bolognani -- Andrea Bolognani / Red Hat / Virtualization -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH] docs: remove devhelp API docs
On Thu, Sep 05, 2019 at 01:34:37PM +0100, Daniel P. Berrangé wrote: > We currently generate two completely separate API references for the > libvirt public API. One at 'docs/html/' and one at 'docs/devhelp/'. > Both are published on the website, but we only link to content in > the 'docs/html/' pages. > > Both are installed in the libvirt-docs sub-RPM, with a full copy > of the website including 'docs/html/' in /usr/share/docs/libvirt-docs, > while the 'docs/devhelp/' content goes to /usr/share/gtk-doc/. The > latter was broken for years until: > > commit ca6f602546cb28658db05f29bc840e04d22d0947 > Author: Andrea Bolognani > Date: Fri May 10 14:54:52 2019 +0200 > > docs: Introduce $(devhelphtml_generated) > > Our XSLT magic generates one Devhelp-compatible HTML file > per documentation module, but so far we have only shipped > and installed documentation for virterror. > > Now that we have $(modules), however, we can generate the > list of files the same way we do for regular documentation > and make sure we always ship and install everything. > > That this bug went unnoticed for so long is a sign of how few > people are using the devhelp docs. The only commits to the devhelp > code since it was first introduced have been fixing various build > problems that hit. > > The only obvious difference between the two sets of docs is the CSS > styling in use. Overall devhelp does not look compelling enough to > justify having two duplicated sets of API docs. Eliminating it will > reduce the amount of XSL code we are carrying in the tree which is > an attractive benefit. > > Signed-off-by: Daniel P. Berrangé > --- > docs/Makefile.am | 38 +-- > docs/devhelp/devhelp.xsl | 131 - > docs/devhelp/home.png| Bin 654 -> 0 bytes > docs/devhelp/html.xsl| 573 --- > docs/devhelp/left.png| Bin 459 -> 0 bytes > docs/devhelp/right.png | Bin 472 -> 0 bytes > docs/devhelp/style.css | 66 - > docs/devhelp/up.png | Bin 406 -> 0 bytes > libvirt.spec.in | 8 - > 9 files changed, 1 insertion(+), 815 deletions(-) > delete mode 100644 docs/devhelp/devhelp.xsl > delete mode 100644 docs/devhelp/home.png > delete mode 100644 docs/devhelp/html.xsl > delete mode 100644 docs/devhelp/left.png > delete mode 100644 docs/devhelp/right.png > delete mode 100644 docs/devhelp/style.css > delete mode 100644 docs/devhelp/up.png Nice cleanup, it failed to apply for me but I did the same changes and looks good. error: cannot apply binary patch to 'docs/devhelp/home.png' without full index line error: docs/devhelp/home.png: patch does not apply This would probably require to use --full-index and/or --binary to format the patch. Reviewed-by: Pavel Hrdina signature.asc Description: PGP signature -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
