Re: [openstack-dev] [OpenStack-docs] [all] Changes to releasenotes and docs build jobs

[Ian Y. Choi]

Thierry Carrez wrote on 11/23/2017 5:38 PM:

Doug Hellmann wrote:

On Nov 22, 2017, at 11:22 AM, Ian Y. Choi  wrote:

Hello,

Maybe there would be some chance to be also considered with PDF builds?

I created an WIP patch on openstack/horizon repository [1] to highlight
which changes to be needed for PDF build support on docs and releasenotes.

Although there is currently one warning using "python setup.py build_sphinx" 
[2],
I think the warning would be quite fine now since using sphinx-build command 
with
"-b latex" option works well and such command execution is how PTI is going 
from my understanding [3].

It does make sense to build PDFs. Do you think we want to always build them?


From now, I have several perspectives:
- Since PDF builds do not require additional modification to existing 
RST documents, always building would be a good idea
 (although few RSTs might have problems - from previous experiences, 
for example, some deprecated usage or

  unsupported unicode characters in font files).
- Some PDF output might be awkward because of image position and table 
layout, but

  those can be easily modified [1].
- Since PDF builds require additional packages in bindep.txt [2], build 
jobs might be slow.






(I am also copying this to openstack-docs mailing list for [4].)

We really really need to stop using that separate mailing list. Now that the 
project teams are managing their own documentation, we should just have the 
docs discussions on the -dev list so everyone can participate.

+1
How about closing that list?



+1

Petr, how do you think about closing that list and encourage current 
openstack-docs subscribers

to use openstack-dev with [docs] tag?


With many thanks,

/Ian

[1] 
https://review.openstack.org/#/c/427826/27/doc/ha-guide/source/networking-ha-l3.rst@16

[2] https://review.openstack.org/#/c/520620/3/bindep.txt

__
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] [OpenStack-docs] [all] Changes to releasenotes and docs build jobs

[Petr Kovar]

On Thu, 23 Nov 2017 09:38:34 +0100
Thierry Carrez  wrote:

> Doug Hellmann wrote:
> > 
> >> On Nov 22, 2017, at 11:22 AM, Ian Y. Choi  wrote:
> >>
> >> Hello,
> >>
> >> Maybe there would be some chance to be also considered with PDF builds?
> >>
> >> I created an WIP patch on openstack/horizon repository [1] to highlight
> >> which changes to be needed for PDF build support on docs and releasenotes.
> >>
> >> Although there is currently one warning using "python setup.py 
> >> build_sphinx" [2],
> >> I think the warning would be quite fine now since using sphinx-build 
> >> command with
> >> "-b latex" option works well and such command execution is how PTI is 
> >> going from my understanding [3].
> > 
> > It does make sense to build PDFs. Do you think we want to always build them?
> > 
> >>
> >> (I am also copying this to openstack-docs mailing list for [4].)
> > 
> > We really really need to stop using that separate mailing list. Now that 
> > the project teams are managing their own documentation, we should just have 
> > the docs discussions on the -dev list so everyone can participate.
> 
> +1
> How about closing that list?

Let me send a final reminder and then we can set the list to read-only in
mailman admin, hopefully. 

Cheers,
pk

__
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] [OpenStack-docs] [all] Changes to releasenotes and docs build jobs

[Thierry Carrez]

Doug Hellmann wrote:
> 
>> On Nov 22, 2017, at 11:22 AM, Ian Y. Choi  wrote:
>>
>> Hello,
>>
>> Maybe there would be some chance to be also considered with PDF builds?
>>
>> I created an WIP patch on openstack/horizon repository [1] to highlight
>> which changes to be needed for PDF build support on docs and releasenotes.
>>
>> Although there is currently one warning using "python setup.py build_sphinx" 
>> [2],
>> I think the warning would be quite fine now since using sphinx-build command 
>> with
>> "-b latex" option works well and such command execution is how PTI is going 
>> from my understanding [3].
> 
> It does make sense to build PDFs. Do you think we want to always build them?
> 
>>
>> (I am also copying this to openstack-docs mailing list for [4].)
> 
> We really really need to stop using that separate mailing list. Now that the 
> project teams are managing their own documentation, we should just have the 
> docs discussions on the -dev list so everyone can participate.

+1
How about closing that list?

-- 
Thierry Carrez (ttx)

__
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] [OpenStack-docs] [all] Changes to releasenotes and docs build jobs

[Doug Hellmann]

> On Nov 22, 2017, at 11:22 AM, Ian Y. Choi  wrote:
> 
> Hello,
> 
> Maybe there would be some chance to be also considered with PDF builds?
> 
> I created an WIP patch on openstack/horizon repository [1] to highlight
> which changes to be needed for PDF build support on docs and releasenotes.
> 
> Although there is currently one warning using "python setup.py build_sphinx" 
> [2],
> I think the warning would be quite fine now since using sphinx-build command 
> with
> "-b latex" option works well and such command execution is how PTI is going 
> from my understanding [3].

It does make sense to build PDFs. Do you think we want to always build them?

> 
> (I am also copying this to openstack-docs mailing list for [4].)

We really really need to stop using that separate mailing list. Now that the 
project teams are managing their own documentation, we should just have the 
docs discussions on the -dev list so everyone can participate.

> 
> 
> With many thanks,
> 
> /Ian
> 
> [1] https://review.openstack.org/#/c/520620/
> [2] https://github.com/sphinx-doc/sphinx/issues/4259
> [3] 
> http://git.openstack.org/cgit/openstack-infra/zuul-jobs/tree/roles/sphinx/tasks/main.yaml#n15
> [4] https://review.openstack.org/#/c/509297/
> 
> Doug Hellmann wrote on 11/23/2017 12:05 AM:
>> Excerpts from Monty Taylor's message of 2017-11-22 07:39:45 -0600:
>> 
>>> * We use -W for all releasenotes builds - this means warnings are always
>>> errors for releasenotes. That shouldn't bother anyone, as most of the
>>> releasenotes content is generated by reno anyway.
>> For projects that never had -W set, there may be invalid RST in old
>> branches. We hit that in ceilometer for mitaka and newton, and since
>> those branches were closed already we used "reno report" to generate
>> static RST pages to replace the reno directives. See
>> https://review.openstack.org/#/c/521548/ for an example of doing this if
>> your project has a similar issue.
>> 
>> Doug
>> 
>> __
>> 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-docs mailing list
> openstack-d...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


__
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