[all] [ptls] [tc] [nova] [neutron] [tripleo] Volunteers that know TeX for PDF community goal

Akihiro Motoki amotoki at gmail.com
Wed Jun 26 06:15:25 UTC 2019


I tried the PDF build on neutron doc.
The neutron doc hit only one error, though I haven't checked the
generated document in detail yet.

1. The PDF generation stopped due to "! Dimension too large." error.
This happens in a sample config file "neutron.conf". I am afraid that
inline text is too long for "verbatim".
As a workaround we can skip inline sample configuration files.

2. The TOC is not suitable for PDF document. It only lists the first two levels.
As a reader of PDF version, I would like to see deeper levels to jump
a specific section directly.
I am not sure where is the setting of the TOC but it is worth improved.

On Tue, Jun 25, 2019 at 8:38 AM Michael Johnson <johnsomor at gmail.com> wrote:
> 3, Oddly, the "configuration" section of our docs didn't render, it's
> just a blank section. Even if the generated configuration guide didn't
> work, I would have expected the RST policies document to come through.
> Even more strange, the configuration guide is linked from another
> section, and it rendered there. This must be one of the billion
> warnings that output.

Just FYI: In case of the neutron doc, I see the "configuration"
section (oslo.config and oslo.policy) successfully.

Thanks,
Akihiro Motoki (amotoki)

On Tue, Jun 25, 2019 at 8:38 AM Michael Johnson <johnsomor at gmail.com> wrote:
>
> I gave this a quick run on Octavia. I did get it to output a PDF with
> our svg included.
>
> I see a few issues right away (beyond the screens and screens of warnings).
>
> How do we want to collect this feedback?  Storyboard stories with a tag?
>
> 1. I needed to add the following bindeps:
> librsvg2-bin [doc platform:dpkg]
> fonts-freefont-otf [doc platform:dpkg]
>
> 2. Relative links come through to the PDF but are broken.
> 3, Oddly, the "configuration" section of our docs didn't render, it's
> just a blank section. Even if the generated configuration guide didn't
> work, I would have expected the RST policies document to come through.
> Even more strange, the configuration guide is linked from another
> section, and it rendered there. This must be one of the billion
> warnings that output.
> 4. We should document how to ignore or re-order the docs. We have an
> internal API reference that comes through as the first section, but is
> of little use to anyone outside the developers. It is also confusing
> as the actual Octavia API-REF link doesn't render.
> 5. The feature matrix tables rendered ok, except the red "X" does not
> (unicode 2716).
> (https://opendev.org/openstack/sphinx-feature-classification)
>
> Michael
>
>
>
>
>
>
>
>
> On Mon, Jun 24, 2019 at 8:59 AM Matthew Treinish <mtreinish at kortar.org> wrote:
> >
> > On Mon, Jun 24, 2019 at 05:26:08PM +0200, Bogdan Dobrelya wrote:
> > > On 24.06.2019 12:29, Alexandra Settle wrote:
> > > > Hi all,
> > > >
> > > > The work for the Train community goal - PDF support for project docs -
> > > > is well underway. [1] Now, we're looking for volunteers to help test the
> > > > implementation.
> > > >
> > > > We'll need someone to help build the docs into PDFs and determine things
> > > > we can fix through tweaks to our docs, or if they're bugs in Sphinx.
> > > > AKA: We need a troubleshoot artist.
> > >
> > > There seems to be an issue [0] for any projects using the badges [1] or
> > > other SVGs in their docs. Also the default levels of nesting of the {\begin
> > > ... \end} stanzas might require additional tunings, like [2]. I'll keep
> > > posting here on the further issues discovered for PDF doc builds for
> > > TripleO. Stay tuned :)
> >
> > The svg in pdf thing was a known issue. When I first looked at building the
> > nova docs with latex/pdf output a few years ago [1] you had to manually
> > convert the images before building the latex. Since then sphinx has added
> > an extension to do this for you:
> >
> > https://www.sphinx-doc.org/en/master/usage/extensions/imgconverter.html
> >
> > You should be able to just add that to the extension list in conf.py and it
> > will convert the svgs at sphinx build time.
> >
> > -Matt Treinish
> >
> > [1] https://opendev.org/openstack/nova/commit/62575dd40e5b7698d9ba54641558246489f0614e
> >
> > >
> > > [0] https://github.com/sphinx-doc/sphinx/issues/4720#issuecomment-372046571
> > > [1] https://governance.openstack.org/tc/badges/
> > > [2] https://review.opendev.org/667114
> > >
> > > >
> > > > If you can volunteer, please add yourself to the wiki table here [2].
> > > > I've added neutron and nova specifically here as we need someone who is
> > > > familiar with the project and it's dependencies to help us get that setup.
> > > >
> > > > Any questions? Reach out.
> > > >
> > > > Cheers,
> > > >
> > > > Alex
> > > >
> > > > [1]
> > > > https://review.opendev.org/#/q/topic:build-pdf-docs+(status:open+OR+status:merged)
> > > >
> > > > [2]
> > > > https://wiki.openstack.org/wiki/Documentation#PDF_for_Project_Docs_-_Community_Goal
> > > >
> > >
> > >
> > > --
> > > Best regards,
> > > Bogdan Dobrelya,
> > > Irc #bogdando
> > >
>



More information about the openstack-discuss mailing list