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

2016-02-20 Thread Dolph Mathews 
On Saturday, February 20, 2016, Thomas Goirand  wrote:

> On 02/19/2016 05:39 AM, Dolph Mathews wrote:
> >
> > On Thu, Feb 18, 2016 at 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)
> >
> >
> > Probably a dumb question, but why do you need to build the HTML docs
> > when you're building a package for Debian?
>
> If the doc is useful at all, why wouldn't it be useful in Debian?


Mike Bayer already answered my question politely.


>
> Cheers,
>
> Thomas Goirand (zigo)
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-02-19 Thread Thomas Goirand 
On 02/19/2016 05:39 AM, Dolph Mathews wrote:
> 
> On Thu, Feb 18, 2016 at 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)
> 
> 
> Probably a dumb question, but why do you need to build the HTML docs
> when you're building a package for Debian?

If the doc is useful at all, why wouldn't it be useful in Debian?

Cheers,

Thomas Goirand (zigo)


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-02-19 Thread Javier Pena 


- Original Message -
> 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.
> 

We have hit the same issue in our automated builds for RDO Trunk, and 
https://bugs.launchpad.net/reno/+bug/1520096 is tracking it for reno.

while it is possible to work around it from the packagers' perspective, it 
would be better to not assume the source is obtained via a git clone.

Cheers,
Javier

> 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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-02-18 Thread Mike Bayer 



On 02/18/2016 04:39 PM, Dolph Mathews wrote:


On Thu, Feb 18, 2016 at 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)


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-requ...@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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-02-18 Thread Paul Belanger 
On Fri, Feb 19, 2016 at 01:17:08AM +0800, 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,
> 
I ran into this in Fedora rawhide a few weeks ago. When talking to Doug in
-infra, there was some discussion to integrate into PBR.  To me, it is just
lacking functionality ATM. For the moment, I dropped reno support on the package
which is not major at this point.

I suspect it will take a few more release to allow packagers to properly use it.

> Thomas Goirand (zigo)
> 
> 
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-02-18 Thread Matthew Thode 
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-requ...@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. 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
entirely.

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)



signature.asc
Description: OpenPGP digital signature
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-02-18 Thread Dolph Mathews 
On Thu, Feb 18, 2016 at 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)
>

Probably a dumb question, but why do you need to build the HTML docs when
you're building a package for Debian?


>
> 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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev