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

Matthew Thode prometheanfire at gentoo.org
Thu Feb 18 22:06:07 UTC 2016

On 02/18/2016 11:17 AM, Thomas Goirand 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)
> 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://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Coming across a bit strong :P

While we (gentoo) are able to build the docs in our git branch based
ebuilds (sys-cluster/nova-2015.2.9999 for liberty for example) we can't
do so in our tag based ebuilds don't think tarballs.openstack.org does
(or should) ship the .git folder.  For us, building docs at install (or
binpkg) generation time is the only way, so this restricts docs for us

If the docs are built and shipped in the tarballs that could work for us
though, we'd just move the files where needed.

-- Matthew Thode (prometheanfire)

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 801 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160218/2ad0e260/attachment.pgp>

More information about the OpenStack-dev mailing list