Open Stack

On 25/06/2019 00:36, Michael Johnson wrote:
> I gave this a quick run on Octavia. I did get it to output a PDF with
> our svg included.
Hooray!
>
> I see a few issues right away (beyond the screens and screens of warnings).
Thanks for sharing :)
>
> How do we want to collect this feedback?  Storyboard stories with a tag?

I think so. Doug pointed me in the direction of: 
https://github.com/openstack/goal-tools (which I was unaware of previously)

I've messaged Stephen to see what his plans are as he's starting the 
entire thing off, and might be best if he generates the story as I'll be 
away as of Thursday.

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