Fwd: [opensuse-cloud] moving doc packages into component packages?
2013/3/14 Christian Berendt
I'm talking about the files included in the packages on the OBS.
For example in openstack-ceilometer-doc I have openstack-ceilometer.init, openstack-ceilometer.logrotate and openstack-ceilometer.spec.
Hi Christian, yes, thats normal, this package is only a source link to the package openstack-ceilometer. Never look or modify the -doc package itself, simply only care about the $component-doc.spec in the $component dir. To make it more obvious, I recommend something like "osc up -u *-doc" in your checkout directory. (yes it would be nice if the build service would do that automatically, but it is not so clever). The package container in OBS named $component-doc only exists to make the -doc.spec file in $component package actually being built. Greetings, Dirk -- To unsubscribe, e-mail: opensuse-cloud+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-cloud+owner@opensuse.org
On 03/15/2013 11:23 AM, Dirk Müller wrote:
The package container in OBS named $component-doc only exists to make the -doc.spec file in $component package actually being built.
Not sure about that. I thought we have the openstack-*-doc packages to separate the build of the documentation from the build of the Python stuff. But looking at my latest build of openstack-nova still shows a lot of Sphinx output. I think done by "python setup.py build_sphinx -b man". Shouldn't we move the man pages to openstack-*-doc, too? Christian. -- Christian Berendt Cloud Computing Solution Architect Tel.: +49-171-5542175 Mail: berendt@b1-systems.de B1 Systems GmbH Osterfeldstraße 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 -- To unsubscribe, e-mail: opensuse-cloud+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-cloud+owner@opensuse.org
2013/3/18 Christian Berendt
The package container in OBS named $component-doc only exists to make the -doc.spec file in $component package actually being built. Not sure about that. I thought we have the openstack-*-doc packages to separate the build of the documentation from the build of the Python stuff.
Both is true.
But looking at my latest build of openstack-nova still shows a lot of Sphinx output. I think done by "python setup.py build_sphinx -b man".
Correct.
Shouldn't we move the man pages to openstack-*-doc, too?
That is the question. so far the policy is to package man pages along the main binaries in the main package, and move the timeconsuming, disk consuming rest (html, pdf docu whatever) into a separate subpackage. Normally, we have %openstack_sphinx_build_manpages_only (which is defined in openstack-suse/macros.openstack) but for nova this macro fails. After a few hours of debugging it we gave up and simply defaulted to the man page only build. Feel free to make the macro work again and remove the sphinx call :) Greetings, Dirk -- To unsubscribe, e-mail: opensuse-cloud+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-cloud+owner@opensuse.org
On 03/18/2013 08:07 PM, Dirk Müller wrote:
2013/3/18 Christian Berendt
: The package container in OBS named $component-doc only exists to make the -doc.spec file in $component package actually being built. Not sure about that. I thought we have the openstack-*-doc packages to separate the build of the documentation from the build of the Python stuff.
Both is true.
But looking at my latest build of openstack-nova still shows a lot of Sphinx output. I think done by "python setup.py build_sphinx -b man".
Correct.
Shouldn't we move the man pages to openstack-*-doc, too?
That is the question. so far the policy is to package man pages along the main binaries in the main package, and move the timeconsuming, disk consuming rest (html, pdf docu whatever) into a separate subpackage.
I guess the man-pages are only useful if shipped alongside the binaries. I'd say it's not obvious to install, say, openstack-nova-doc to get them. Once could split the doc package further into doc-html, doc-man, doc-pdf, ...) like some other packages do but I'm unsure if that is worth the effort.
Normally, we have %openstack_sphinx_build_manpages_only (which is defined in openstack-suse/macros.openstack) but for nova this macro fails. After a few hours of debugging it we gave up and simply defaulted to the man page only build. Feel free to make the macro work again and remove the sphinx call :)
It should be noted that you are always using Sphinx to build the documentation, i.e. regardless of any RPM macro. It's just that "setup.py build_sphinx" loads the plugins that are usually configured in doc/source/conf.py (Sphinx config). What makes things is slow is that OpenStack likes to use the autodoc Sphinx plugin. It recursively parses the whole source tree for docstrings to include in the API documentation. Of course that makes little sense for manpages so there are some options here: 1) Revive %openstack_sphins_build_manpages_only What it basically did is to copy the manpage doc tree and the Sphinx config into a fresh directory. This way, autodoc can't find any additional sources and hence the build is fast! 2) Have a separate man-page Sphinx configuration that is upstreamable. Less hacky but you may have a hard time explaining upstream hackers used to do everything from git what the benefits are. 3) Add some check to doc/source/conf.py to only include those plugins if the build target is not 'man' I think I'll invest some time in option 3. In the end this helps everyone an we get rid of yet another RPM macro. -- With kind regards, Sascha Peilicke SUSE Linux GmbH, Maxfeldstr. 5, D-90409 Nuernberg, Germany GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer HRB 16746 (AG Nürnberg) -- To unsubscribe, e-mail: opensuse-cloud+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-cloud+owner@opensuse.org
participants (3)
-
Christian Berendt
-
Dirk Müller
-
Sascha Peilicke