Add with_doc conditional over -doc subpackage

[chkumar246]

All the RDO packages contains -doc subpackage which contains docs for the specific projects. Sometime while building doc subpackage, we might need to add more dependencies or remove some javascript/css files in order to avoid dependency and if any of the dependency is not packaged, the rpm package building will break in order to avoid that it would be good to introduce with_doc conditional for -doc subpackage. So that we can enable or disable doc building step.

What to improve:

1. Clone openstack-swift spec file git clone https://github.com/rdo-packages/swift-distgit
2. Go to swift-distgit and open openstack-swift.spec in editor.
3. Define %global with_doc 1 at the top of spec file.
4. Go to -doc subpackage,
5. Above that add %if 0%{?with_doc}, it will start the doc_guard
6. Go to %description of -doc subpackage and add %endif to end the doc_guard.
7. Add the same doc_guard condition defined in step 5 just above %{__python2} setup.py build_sphinx and end the doc_guard at rm -rf doc/build/html/.{doctrees,buildinfo} as stated in step 6.
8. Perform the step 7 for adding doc_guard for %files docs section.
9. Once done! Make changes, add and commit it and send a Gerrit Review.

For example: you can check the spec file of python-os-traits or python-osprofiler

Below is the list of packages which need same fixes:

• [X] openstack-sahara review
• [ ] openstack-ceilometer
• [X] openstack-swift review
• [ ] openstack-neutron
• [ ] openstack-zaqar
• [ ] python-oslo-cache
• [ ] python-oslo-concurrency
• [ ] python-oslo-config
• [ ] python-oslo-context
• [ ] python-oslo-db
• [ ] python-oslo-i18n
• [ ] python-oslo-log
• [ ] python-oslo-messaging
• [ ] python-oslo-middleware
• [ ] python-oslo-policy
• [ ] python-oslo-privsep
• [ ] python-oslo-reports
• [ ] python-oslo-rootwrap
• [ ] python-oslo-serialization
• [ ] python-oslo-service
• [ ] python-oslo-sphinx
• [ ] python-oslotest
• [ ] python-oslo-utils
• [ ] python-oslo-versionedobjects
• [ ] python-oslo-vmware
• [X] python-osprofiler review

Mentor: Jon Schlueter - IRC: jschlueter github: yazug Note: Pick one of the package and comment in the comment box with review link.

[apevec]

@yazug should man pages be included in %if with_doc or outside?

[yazug]

man page generation and inclusion if it goes into main package and not just the -doc sub-package should be preserved. If it's going into -doc sub-package then it should be guarded with the %if with_doc

[yazug]

python-osprofiler - https://review.rdoproject.org/r/7781 add with_doc guard for building docs

[yazug]

https://review.rdoproject.org/r/#/q/topic:with_doc_guard_easyfix

[yazug]

openstack-sahara https://review.rdoproject.org/r/7786 Add with_doc guards for building -doc sub-package

[OGtrilliams]

openstack-swift 😸 https://review.rdoproject.org/r/7789

[OGtrilliams]

python-oslo-concurrency - https://review.rdoproject.org/r/8087

[dsilakov]

Found this PR while rebuilding openstack packages without documentation.

Guys, what about possibility to disable doc generation by some global macro as it is already done in some other OpenStack packages?

This can be easily implemented by replacing hardcoded "%global with_doc 1" with a definition that take into account value of other macro ("_without_doc" is usually used for this:

%global with_doc %{!?_without_doc:1}%{?_without_doc:0}