Open Stack

Michael Johnson <johnsomor at gmail.com> writes:

> 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]

We should add those globally in the job definition, and optionally in
the project bindep file.

> 2. Relative links come through to the PDF but are broken.

Can you give an example of a link that didn't work? I suspect this has
to do with using HTML links instead of :ref: or :doc: links that Sphinx
knows how to resolve.

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

I'll defer to our information architects on the exact ordering, but I
agree that we should be emphasizing user-facing content over contributor
content. That likely means reordering the toctree directive in the root
of several projects. It is *possible* to specify a different top-level
document to use for controlling the order of content in the PDF build,
but I don't recommend doing that because that will give you 2 separate
toctrees to keep up to date as new content is added, and we're trying to
achieve the first iteration of this goal without adding a ton of new
maintenance burden for teams.

> 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
>> >
>

-- 
Doug