Hello, I understand that there was a push [1] to make PDFs available for download from the published pages on docs.openstack.org for the various guides (Sphinx projects). Is there any steam left in this initiative? The next best thing is to have something at the repository level that people can work with. Currently, there are a limited number of guides that can be converted to PDF from the openstack-manuals repository. What is the suggested implementation for individual projects? Thanks, Peter Matulis [1]: https://etherpad.opendev.org/p/train-pdf-support-goal
On 2021-03-03 14:36:01 -0500 (-0500), Peter Matulis wrote:
I understand that there was a push [1] to make PDFs available for download from the published pages on docs.openstack.org for the various guides (Sphinx projects). Is there any steam left in this initiative?
The next best thing is to have something at the repository level that people can work with. Currently, there are a limited number of guides that can be converted to PDF from the openstack-manuals repository. What is the suggested implementation for individual projects?
I may be misunderstanding, but can you elaborate on what's missing which you expected to find? There are, for example, PDFs like: https://docs.openstack.org/nova/latest/doc-nova.pdf Is it that we're not building those for some projects yet which you want added, or that there are other non-project-specific documents which need similar treatment, or simply that we're not doing enough to make the existence of the PDF versions discoverable? -- Jeremy Stanley
On Wed, Mar 3, 2021 at 2:47 PM Jeremy Stanley <fungi@yuggoth.org> wrote:
I may be misunderstanding, but can you elaborate on what's missing which you expected to find? There are, for example, PDFs like:
https://docs.openstack.org/nova/latest/doc-nova.pdf
Is it that we're not building those for some projects yet which you want added, or that there are other non-project-specific documents which need similar treatment, or simply that we're not doing enough to make the existence of the PDF versions discoverable?
How do I get a download PDF link like what is available in the published pages of the Nova project? Where is that documented? In short, yes, I am interested in having downloadable PDFs for the projects that I maintain: https://opendev.org/openstack/charm-guide https://opendev.org/openstack/charm-deployment-guide
On 2021-03-03 15:05:10 -0500 (-0500), Peter Matulis wrote: [...]
How do I get a download PDF link like what is available in the published pages of the Nova project? Where is that documented?
In short, yes, I am interested in having downloadable PDFs for the projects that I maintain:
https://opendev.org/openstack/charm-guide https://opendev.org/openstack/charm-deployment-guide
The official goal document is still available here: https://governance.openstack.org/tc/goals/selected/train/pdf-doc-generation.... Some technical detail can also be found in the earlier docs spec: https://specs.openstack.org/openstack/docs-specs/specs/ocata/build-pdf-from-... A bit of spelunking in Git history turns up, for example, this change implementing PDF generation for openstack/ironic (you can find plenty more if you hunt): https://review.opendev.org/680585 I expect you would just do something similar to that. If memory serves (it's been a couple years now), each project hit slightly different challenges as no two bodies of documentation are every quite the same. You'll likely have to dig deep occasionally in Sphinx and LaTeX examples to iron things out. One thing which would have been nice as an output of that cycle goal was if the PTI section for documentation was updated with related technical guidance on building PDFs, but it's rather lacking in that department still: https://governance.openstack.org/tc/reference/project-testing-interface.html... If you can come up with a succinct summary for what's needed, I expect adding it there would be really useful to others too. -- Jeremy Stanley
On 3/3/21 9:30 PM, Jeremy Stanley wrote:
On 2021-03-03 15:05:10 -0500 (-0500), Peter Matulis wrote: [...]
How do I get a download PDF link like what is available in the published pages of the Nova project? Where is that documented?
On each project's documentation page, there is a "Download PDF" button, at the top, near to the "Report a Bug".
In short, yes, I am interested in having downloadable PDFs for the projects that I maintain:
https://opendev.org/openstack/charm-guide https://opendev.org/openstack/charm-deployment-guide
The official goal document is still available here:
https://governance.openstack.org/tc/goals/selected/train/pdf-doc-generation....
Some technical detail can also be found in the earlier docs spec:
https://specs.openstack.org/openstack/docs-specs/specs/ocata/build-pdf-from-...
A bit of spelunking in Git history turns up, for example, this change implementing PDF generation for openstack/ironic (you can find plenty more if you hunt):
https://review.opendev.org/680585
I expect you would just do something similar to that. If memory serves (it's been a couple years now), each project hit slightly different challenges as no two bodies of documentation are every quite the same. You'll likely have to dig deep occasionally in Sphinx and LaTeX examples to iron things out.
One thing which would have been nice as an output of that cycle goal was if the PTI section for documentation was updated with related technical guidance on building PDFs, but it's rather lacking in that department still:
https://governance.openstack.org/tc/reference/project-testing-interface.html...
If you can come up with a succinct summary for what's needed, I expect adding it there would be really useful to others too.
-- Best regards, Bogdan Dobrelya, Irc #bogdando
Peter, Feel free to message me on IRC (johnsom) if you run into questions about enabling the PDF docs for your projects. I did the work for Octavia so might have some answers. Michael On Thu, Mar 4, 2021 at 12:36 AM Bogdan Dobrelya <bdobreli@redhat.com> wrote:
On 3/3/21 9:30 PM, Jeremy Stanley wrote:
On 2021-03-03 15:05:10 -0500 (-0500), Peter Matulis wrote: [...]
How do I get a download PDF link like what is available in the published pages of the Nova project? Where is that documented?
On each project's documentation page, there is a "Download PDF" button, at the top, near to the "Report a Bug".
In short, yes, I am interested in having downloadable PDFs for the projects that I maintain:
https://opendev.org/openstack/charm-guide https://opendev.org/openstack/charm-deployment-guide
The official goal document is still available here:
https://governance.openstack.org/tc/goals/selected/train/pdf-doc-generation....
Some technical detail can also be found in the earlier docs spec:
https://specs.openstack.org/openstack/docs-specs/specs/ocata/build-pdf-from-...
A bit of spelunking in Git history turns up, for example, this change implementing PDF generation for openstack/ironic (you can find plenty more if you hunt):
https://review.opendev.org/680585
I expect you would just do something similar to that. If memory serves (it's been a couple years now), each project hit slightly different challenges as no two bodies of documentation are every quite the same. You'll likely have to dig deep occasionally in Sphinx and LaTeX examples to iron things out.
One thing which would have been nice as an output of that cycle goal was if the PTI section for documentation was updated with related technical guidance on building PDFs, but it's rather lacking in that department still:
https://governance.openstack.org/tc/reference/project-testing-interface.html...
If you can come up with a succinct summary for what's needed, I expect adding it there would be really useful to others too.
-- Best regards, Bogdan Dobrelya, Irc #bogdando
~ Update ~ I've managed to build a PDF locally using a tox target: $ tox -e deploy-guide-pdf deploy-guide/build/pdf/DeploymentGuide.pdf For my local web server, the resulting HTML has an icon with this download link: http://<domain>//doc-charm-deployment-guide.pdf Which doesn't work. How do I fix that? And especially, how do I get Zuul to do it? My PR is here: https://review.opendev.org/c/openstack/charm-deployment-guide/+/782581 On Thu, Mar 4, 2021 at 2:13 PM Michael Johnson <johnsomor@gmail.com> wrote:
Peter,
Feel free to message me on IRC (johnsom) if you run into questions about enabling the PDF docs for your projects. I did the work for Octavia so might have some answers.
Michael
On Thu, Mar 4, 2021 at 12:36 AM Bogdan Dobrelya <bdobreli@redhat.com> wrote:
On 3/3/21 9:30 PM, Jeremy Stanley wrote:
On 2021-03-03 15:05:10 -0500 (-0500), Peter Matulis wrote: [...]
How do I get a download PDF link like what is available in the published pages of the Nova project? Where is that documented?
On each project's documentation page, there is a "Download PDF" button, at the top, near to the "Report a Bug".
In short, yes, I am interested in having downloadable PDFs for the projects that I maintain:
https://opendev.org/openstack/charm-guide https://opendev.org/openstack/charm-deployment-guide
The official goal document is still available here:
https://governance.openstack.org/tc/goals/selected/train/pdf-doc-generation....
Some technical detail can also be found in the earlier docs spec:
https://specs.openstack.org/openstack/docs-specs/specs/ocata/build-pdf-from-...
A bit of spelunking in Git history turns up, for example, this change implementing PDF generation for openstack/ironic (you can find plenty more if you hunt):
https://review.opendev.org/680585
I expect you would just do something similar to that. If memory serves (it's been a couple years now), each project hit slightly different challenges as no two bodies of documentation are every quite the same. You'll likely have to dig deep occasionally in Sphinx and LaTeX examples to iron things out.
One thing which would have been nice as an output of that cycle goal was if the PTI section for documentation was updated with related technical guidance on building PDFs, but it's rather lacking in that department still:
https://governance.openstack.org/tc/reference/project-testing-interface.html...
If you can come up with a succinct summary for what's needed, I expect adding it there would be really useful to others too.
-- Best regards, Bogdan Dobrelya, Irc #bogdando
On 2021-03-29 16:34:16 -0400 (-0400), Peter Matulis wrote: [...]
For my local web server, the resulting HTML has an icon with this download link: http://<domain>//doc-charm-deployment-guide.pdf
Which doesn't work.
How do I fix that? And especially, how do I get Zuul to do it? [...]
Looking at the console for the docs build on your change, it seems to be skipping PDF building in the run phase because of this check: <URL: https://opendev.org/openstack/openstack-zuul-jobs/src/commit/01746b6df094c25... > Your change uses deploy-guide-pdf as its tox testenv instead of the default "pdf-docs" value set by the build-pdf-docs role. You could override it in a vars block within a custom job, but probably easier to adjust your tox.ini to what the standard build-openstack-deploy-guide job expects. Alternatively, you might adjust the job definition here, maybe it was an oversight (I don't immediately spot any examples of projects publishing PDFs with that job specifically, though my search was far from complete): <URL: https://opendev.org/openstack/openstack-zuul-jobs/src/commit/01746b6df094c25... > -- Jeremy Stanley
I changed the testenv to 'pdf-docs' and the build is still being skipped. Do I need to submit a PR to have this [1] set to 'false'? [1]: https://opendev.org/openstack/openstack-zuul-jobs/src/commit/01746b6df094c25... On Mon, Mar 29, 2021 at 5:56 PM Jeremy Stanley <fungi@yuggoth.org> wrote:
On 2021-03-29 16:34:16 -0400 (-0400), Peter Matulis wrote: [...]
For my local web server, the resulting HTML has an icon with this download link: http://<domain>//doc-charm-deployment-guide.pdf
Which doesn't work.
How do I fix that? And especially, how do I get Zuul to do it? [...]
Looking at the console for the docs build on your change, it seems to be skipping PDF building in the run phase because of this check:
<URL: https://opendev.org/openstack/openstack-zuul-jobs/src/commit/01746b6df094c25...
Your change uses deploy-guide-pdf as its tox testenv instead of the default "pdf-docs" value set by the build-pdf-docs role. You could override it in a vars block within a custom job, but probably easier to adjust your tox.ini to what the standard build-openstack-deploy-guide job expects. Alternatively, you might adjust the job definition here, maybe it was an oversight (I don't immediately spot any examples of projects publishing PDFs with that job specifically, though my search was far from complete):
<URL: https://opendev.org/openstack/openstack-zuul-jobs/src/commit/01746b6df094c25...
-- Jeremy Stanley
On 2021-03-29 19:47:24 -0400 (-0400), Peter Matulis wrote:
I changed the testenv to 'pdf-docs' and the build is still being skipped.
Do I need to submit a PR to have this [1] set to 'false'?
[1]: https://opendev.org/openstack/openstack-zuul-jobs/src/commit/01746b6df094c25... [...]
Oh, yep that'll need to be adjusted or overridden as well. I see that https://review.opendev.org/678077 explicitly chose not to do PDF builds for deploy guides for the original PDF docs implementation a couple of years ago. Unfortunately the commit message doesn't say why, but maybe this is a good opportunity to start. However, many (most?) API projects seem to include their deployment guides in their software Git repos, so switching this on for everyone might break their deploy guide builds. If we combine it with an expectation for a deploy-guide-specific PDF building tox testenv like you had previously, then it would get safely skipped by any projects without that testenv defined. -- Jeremy Stanley
On Mon, Mar 29, 2021 at 8:09 PM Jeremy Stanley <fungi@yuggoth.org> wrote:
On 2021-03-29 19:47:24 -0400 (-0400), Peter Matulis wrote:
I changed the testenv to 'pdf-docs' and the build is still being skipped.
Do I need to submit a PR to have this [1] set to 'false'?
[1]:
https://opendev.org/openstack/openstack-zuul-jobs/src/commit/01746b6df094c25... [...]
Oh, yep that'll need to be adjusted or overridden as well. I see that https://review.opendev.org/678077 explicitly chose not to do PDF builds for deploy guides for the original PDF docs implementation a couple of years ago. Unfortunately the commit message doesn't say why, but maybe this is a good opportunity to start.
Any other thoughts before I propose a change to the below? https://opendev.org/openstack/openstack-zuul-jobs/src/branch/master/zuul.d/j... However, many (most?) API projects seem to include their
deployment guides in their software Git repos, so switching this on for everyone might break their deploy guide builds. If we combine it with an expectation for a deploy-guide-specific PDF building tox testenv like you had previously, then it would get safely skipped by any projects without that testenv defined. -- Jeremy Stanley
On 07.04.21 03:16, Peter Matulis wrote:
On Mon, Mar 29, 2021 at 8:09 PM Jeremy Stanley <fungi@yuggoth.org <mailto:fungi@yuggoth.org>> wrote:
On 2021-03-29 19:47:24 -0400 (-0400), Peter Matulis wrote: > I changed the testenv to 'pdf-docs' and the build is still being skipped. > > Do I need to submit a PR to have this [1] set to 'false'? > > [1]: > https://opendev.org/openstack/openstack-zuul-jobs/src/commit/01746b6df094c25... <https://opendev.org/openstack/openstack-zuul-jobs/src/commit/01746b6df094c25f0cd67690b44adca0fb4ee1fd/zuul.d/jobs.yaml#L970> [...]
Oh, yep that'll need to be adjusted or overridden as well. I see that https://review.opendev.org/678077 <https://review.opendev.org/678077> explicitly chose not to do PDF builds for deploy guides for the original PDF docs implementation a couple of years ago. Unfortunately the commit message doesn't say why, but maybe this is a good opportunity to start.
Any other thoughts before I propose a change to the below?
https://opendev.org/openstack/openstack-zuul-jobs/src/branch/master/zuul.d/j... <https://opendev.org/openstack/openstack-zuul-jobs/src/branch/master/zuul.d/jobs.yaml#L970>
I think it will not be enough, you need to set tox_pdf_envlist as well. I suggest to propose such a change and make two tests - with depends-on: 1) For your repo to show that you build the deploy-guide as PDF and have it in artifacts uploaded 2) For another use of the job that builds the normal docs as well to check that the PDF for the deploy-guide is build and not the normal docs. Andreas -- Andreas Jaeger aj@suse.com Twitter: jaegerandi SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, D 90409 Nürnberg (HRB 36809, AG Nürnberg) GF: Felix Imendörffer GPG fingerprint = EF18 1673 38C4 A372 86B1 E699 5294 24A3 FF91 2ACB
participants (5)
-
Andreas Jaeger
-
Bogdan Dobrelya
-
Jeremy Stanley
-
Michael Johnson
-
Peter Matulis