[openstack-dev] [all] Please do *not* use git (and specifically "git log") when generating the docs

Mike Bayer mbayer at redhat.com
Fri Feb 19 02:29:54 UTC 2016



On 02/18/2016 04:39 PM, Dolph Mathews wrote:
>
> On Thu, Feb 18, 2016 at 11:17 AM, Thomas Goirand <zigo at debian.org
> <mailto:zigo at debian.org>> wrote:
>
>     Hi,
>
>     I've seen Reno doing it, then some more. It's time that I raise the
>     issue globally in this list before the epidemic spreads to the whole of
>     OpenStack ! :)
>
>     The last occurence I have found is in oslo.config (but please keep in
>     mind this message is for all projects), which has, its
>     doc/source/conf.py:
>
>     git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'",
>                 "--date=local","-n1"]
>     html_last_updated_fmt = subprocess.check_output(git_cmd,
>                                                      stdin=subprocess.PIPE)
>
>
> Probably a dumb question, but why do you need to build the HTML docs
> when you're building a package for Debian?

Sphinx builds in many formats, not just HTML, and includes among others 
man page format which is probably relevant to a Debian package.



>
>
>     Of course, the .git folder is *NOT* available when building a package in
>     Debian (and more generally, in downstream distros). This means that this
>     kind of joke *will* break the build of the packages when they also build
>     the docs of your project. And consequently, the package maintainers have
>     to patch out the above lines from conf.py. It'd be best if it wasn't
>     needed to do so.
>
>     As a consequence, it is *not ok* to do "git log" anywhere in the sphinx
>     docs. Please keep this in mind.
>
>     More generally, it is wrong to assume that even the git command is
>     present. For Mitaka b2, I had to add git as build-dependency on nearly
>     all server packages, otherwise they would FTBFS (fail to build from
>     source). This is plain wrong and makes no sense. I hope this can be
>     reverted somehow.
>
>     Thanks in advance for considering the above, and to try to see things
>     from the package maintainer's perspective,
>     Cheers,
>
>     Thomas Goirand (zigo)
>
>
>     __________________________________________________________________________
>     OpenStack Development Mailing List (not for usage questions)
>     Unsubscribe:
>     OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>     <http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe>
>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
>
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



More information about the OpenStack-dev mailing list