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/62575dd40e5b7698d9ba54641558246489...

[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:m...)

[2] https://wiki.openstack.org/wiki/Documentation#PDF_for_Project_Docs_-_Communi...

-- Best regards, Bogdan Dobrelya, Irc #bogdando

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@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/62575dd40e5b7698d9ba54641558246489...

...

[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:m...)

[2] https://wiki.openstack.org/wiki/Documentation#PDF_for_Project_Docs_-_Communi...

-- Best regards, Bogdan Dobrelya, Irc #bogdando

On Tuesday, 25 June 2019 15:17:50 CEST Doug Hellmann wrote:

Michael Johnson johnsomor@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.

I think I've seen this issue while testing the generation locally for Sahara:

LaTeX Warning: Hyper reference `user/hadoop-swift::doc' on page 6 undefined on input line 368. (and many others similar warnings)

The example above comes from https://opendev.org/openstack/sahara/src/branch/ master/doc/source/intro/overview.rst

To get more information on how to enable swift support see :doc:`../user/hadoop-swift`.

The generate document does not contain any hyperlink, but the replaced text is correct.

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@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@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@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/62575dd40e5b7698d9ba54641558246489...

...

[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:m...)

[2] https://wiki.openstack.org/wiki/Documentation#PDF_for_Project_Docs_-_Communi...

-- Best regards, Bogdan Dobrelya, Irc #bogdando

On Wed, Jun 26, 2019 at 6:24 PM Stephen Finucane sfinucan@redhat.com wrote:

On Mon, 2019-06-24 at 16:36 -0700, Michael Johnson wrote:

...

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 think this happens because it renders pages in the order that it encounters them. If you ensure there's a table of contents on the index page of each subsection ('/user', '/admin', '/config', ...), and that there's a top-level table of contents linking to each of these from your 'master_doc' as defined in 'conf.py (typically 'index') then things _should_ render in the correct order. These table of contents _could_ be hidden, though I haven't tested that yet.

I plan to rework the nova docs according to the above...as soon as I get the darn thing building.

I found time to explore TOC related stuffs a bit deeper for the neutron document. I share my experiences below.

BTW, it looks better to prepare some place to share our knowledge, etherpad?

P.S. I still have a trouble in sample config files (relative paths and literalinclude), but it is a different topic. It would be nice if someone can dive into this topic.

Let's start the detail on TOC.

[TOC structure]

It seems the HTML and LaTeX builders handle toctree in a bit different manners. The following are what I hit. I noted solutions/workarounds for individual items, but another solution is to use a separate top page (See "Separate top page" below).

The following style like [1] is used commonly in our OpenStack project documents. This is useful for HTML documents but it is not for PDF documents :-(

Installation Guide ------------------

.. toctree:: :maxdepth: 2

install/index

leads to the following TOC in a PDF doc. It does not sound nice :p

1 Installation Guide 1.1 Networking service Installation Guide 2 Networking Guide 2.1 OpenStack Networking Guide

To avoid this, we need to use toctree without sections in the top page.

[Search page]

"search" page works only for HTML pages. It is meaningless in PDF docs. The straight-forward solution is to use "only" directive.

.. only:: html

* :ref:`search`

[URLs in toctree]

...

It is also confusing as the actual Octavia API-REF link doesn't render.

It seems the latex builder does not consider a direct link in toctree like below. In case of the neutron doc, I created a new rst file to point the API reference [2], but it is just a workaround.

.. toctree :maxdepth: 2

... API Reference https://developer.openstack.org/api-ref/network/ ...

[Separate top page]

You can also have a separate top page (master_doc) for PDF document [3]. We usually specify a file specified in 'master_doc' (default: 'index') to 'startdocname' but we can use a different one.

latex_documents = [ ('pdf-index', 'neutron.tex', u'Neutron Documentation', u'Neutron development team', 'manual'), ]

[TOC level]

By default, the first two levels are shown in TOC. If you would like to show deeper levels, you need to set 'tocdepth'. To show the fourth level, the following needs to be configured in doc/source/conf.py [4] (The number starts from 0, so 3 means the fourth level):

latex_elements = { 'preamble': r'\setcounter{tocdepth}{3}', }

[Stop generating the index]

It seems the latex builder always tries to generate the module index by default, but if we do not load all modules in a document the index would be partial and not useful. To disable this, the following configuration in doc/source/conf.py would work:

latex_elements = { 'makeindex': '', 'printindex': '', }

[1] https://opendev.org/openstack/neutron/blame/commit/9d4161f955681c83bf121d84f... [2] https://review.opendev.org/#/c/667345/6/doc/source/reference/rest-api.rst [3] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-latex_... [4] 'preamble' in https://www.sphinx-doc.org/en/master/latex.html#the-latex-elements-configura...

-- Akihiro Motoki (irc:amotoki)