Re: [openstack-dev] [all] Changes to releasenotes and docs build jobs
On 11/22/2017 07:39 AM, Monty Taylor wrote:
Hey everybody!
Following recent changes [0] in the PTI [1][2] we're rolling out some
changes to the build-openstack-releasenotes and
build-openstack-sphinx-docs jobs. If you see patches with the topic
'updated-pti' - they are in service of this.
The most important thing to be aware of is that we'll no longer be using
tox for either of them. There are a few reasons for that - the one
that's most important to me is that it allows us to use the exact same
docs and releasenotes build jobs for python, go, javascript or any other
language without needing to add python build tooling to non-python
repos. We'll also align more with how readthedocs does things in the
broader python ecosystem.
It's also worth reminding people that we've NEVER used 'tox -edocs' in
the gate for docs jobs - so anyone who has additional things in their
docs environment has not been having those things run. For folks running
doc8, we recommend adding those checks to your pep8 environment instead.
It's also worth noting that we're adding support for a
doc/requirements.txt file (location chosen for alignment readthedocs) to
express requirements needed for all docs (for both releasenotes and
docs). We'll start off falling back to test-requirements.txt ... but, we
recommend splitting doc related requirements into doc/requirements.txt -
since that will mean not needing to install Sphinx when doing tox
unittests.
Specific info
=
Releasenotes
The patches for releasenotes have been approved and merged.
* 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.
* We're temporarily installing the project to get version number. Doing
this will be removed as soon as the changes in
topic:releasenotes-version land. Note this only changes the version
number on the front page, not what is shown. topics:releasenotes-version
The majority of the changes for this have merged, let's move forward:
https://review.openstack.org/526850
* Installs dependencies via bindep for doc environment.
* doc/requirements.txt is used for installation of python dependencies.
Things like whereto or openstackdocstheme should go there.
Documentation builds
* We use -W only if setup.cfg sets it
* Installs dependencies via bindep for doc environment. Binary deps,
such as graphviz, should be listed in bindep and marked with a 'doc' tag.
* doc/requirements.txt is used for installation of python dependencies.
Things like whereto or openstackdocstheme should go there.
* tox_install.sh used to install project if it exists. Because of the
current situation with neutron and horizon plugins it's necessary to run
tox_install.sh if it exists as part of setup. We eventually want to make
that go away, but that's a different effort. There are seven repos with
a problematic tox_install.sh - patches will be arriving to fix them, and
we won't land the build-openstack-sphinx-docs changes until they have
all landed.
For many projects, tox_install.sh is not needed at all and can be easily
replaced. Changes are up for those that we can replace easily - and many
are already merged. For open changes, see
https://review.openstack.org/#/q/status:open++topic:rm-tox_install
Please review and merge,
Andreas
We've prepared these with a bunch of depends-on patches across a
collection of projects, so we don't anticipate much in the way of pain
... but life happens, so if you notice anything go south with
releasenotes or sphinx jobs, please let us know and we can help solve
any issues.
Thanks!
Monty
[0] https://review.openstack.org/#/c/509868
[1] https://review.openstack.org/#/c/508694
[2]
https://governance.openstack.org/tc/reference/project-testing-interface.html
__
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
--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Felix Imendörffer, Jane Smithard, Graham Norton,
HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
__
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] Changes to releasenotes and docs build jobs
On 2017-11-22 18:26, James E. Blair wrote:
> Monty Taylor writes:
>
>> * We use -W only if setup.cfg sets it
>>
>> * Installs dependencies via bindep for doc environment. Binary deps,
>> such as graphviz, should be listed in bindep and marked with a 'doc'
>> tag.
>>
>> * doc/requirements.txt is used for installation of python dependencies.
>> Things like whereto or openstackdocstheme should go there.
>
> Should we add this info to the infra manual?
>
> Similar to this?
>
> https://docs.openstack.org/infra/manual/drivers.html#package-requirements
Yes, I suggest to update it. The PTI documents doc/requirements.txt but
the link above should be correct and mention it as well,
Andreas
--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Felix Imendörffer, Jane Smithard, Graham Norton,
HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
__
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] Changes to releasenotes and docs build jobs
Monty Taylor writes: > * We use -W only if setup.cfg sets it > > * Installs dependencies via bindep for doc environment. Binary deps, > such as graphviz, should be listed in bindep and marked with a 'doc' > tag. > > * doc/requirements.txt is used for installation of python dependencies. > Things like whereto or openstackdocstheme should go there. Should we add this info to the infra manual? Similar to this? https://docs.openstack.org/infra/manual/drivers.html#package-requirements -Jim __ 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] Changes to releasenotes and docs build jobs
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]. (I am also copying this to openstack-docs mailing list for [4].) 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 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] Changes to releasenotes and docs build jobs
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-dev] [all] Changes to releasenotes and docs build jobs
Hey everybody! Following recent changes [0] in the PTI [1][2] we're rolling out some changes to the build-openstack-releasenotes and build-openstack-sphinx-docs jobs. If you see patches with the topic 'updated-pti' - they are in service of this. The most important thing to be aware of is that we'll no longer be using tox for either of them. There are a few reasons for that - the one that's most important to me is that it allows us to use the exact same docs and releasenotes build jobs for python, go, javascript or any other language without needing to add python build tooling to non-python repos. We'll also align more with how readthedocs does things in the broader python ecosystem. It's also worth reminding people that we've NEVER used 'tox -edocs' in the gate for docs jobs - so anyone who has additional things in their docs environment has not been having those things run. For folks running doc8, we recommend adding those checks to your pep8 environment instead. It's also worth noting that we're adding support for a doc/requirements.txt file (location chosen for alignment readthedocs) to express requirements needed for all docs (for both releasenotes and docs). We'll start off falling back to test-requirements.txt ... but, we recommend splitting doc related requirements into doc/requirements.txt - since that will mean not needing to install Sphinx when doing tox unittests. Specific info = Releasenotes The patches for releasenotes have been approved and merged. * 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. * We're temporarily installing the project to get version number. Doing this will be removed as soon as the changes in topic:releasenotes-version land. Note this only changes the version number on the front page, not what is shown. topics:releasenotes-version * Installs dependencies via bindep for doc environment. * doc/requirements.txt is used for installation of python dependencies. Things like whereto or openstackdocstheme should go there. Documentation builds * We use -W only if setup.cfg sets it * Installs dependencies via bindep for doc environment. Binary deps, such as graphviz, should be listed in bindep and marked with a 'doc' tag. * doc/requirements.txt is used for installation of python dependencies. Things like whereto or openstackdocstheme should go there. * tox_install.sh used to install project if it exists. Because of the current situation with neutron and horizon plugins it's necessary to run tox_install.sh if it exists as part of setup. We eventually want to make that go away, but that's a different effort. There are seven repos with a problematic tox_install.sh - patches will be arriving to fix them, and we won't land the build-openstack-sphinx-docs changes until they have all landed. We've prepared these with a bunch of depends-on patches across a collection of projects, so we don't anticipate much in the way of pain ... but life happens, so if you notice anything go south with releasenotes or sphinx jobs, please let us know and we can help solve any issues. Thanks! Monty [0] https://review.openstack.org/#/c/509868 [1] https://review.openstack.org/#/c/508694 [2] https://governance.openstack.org/tc/reference/project-testing-interface.html __ 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
