[OpenStack-docs] Asking reviews for draft PDF styling results + moving styles into openstackdocstheme?

Lana Brindley openstack at lanabrindley.com
Mon Feb 6 02:01:34 UTC 2017

On 06/02/17 08:54, Ian Y. Choi wrote:
> Hello,
> Me and SeongSoo have been collaborating a lot to apply better customized styles
> to PDF documents from rst-based guide documents (spec is available at [1]).
> Applying styles from documents with a basic pdflatex theme (example: [2, 3, 4]) have not been easy for us.
> However, thanks to the new sphinx version support [5], lots of latest styling options described
> in Sphinx documentation [6] are now well-applicable to openstack-manuals!
> The draft PDF styling results are available at [7].
> You can check new PDF files by clicking "gate-openstack-manuals-tox-doc-publish-checkbuild"
> and "(pdf)" links for arch-design, ha-guide, image-guide, and user-guide (for example: [8]).
> More detailed descriptions are available at Etherpad [9].
> I would like to ask team members to review the new draft PDF styling results,
> and if you are fine, then me and SeongSoo want to migrate current python and latex styling files
> into openstackdocstheme and then polish [7] to make use of a new openstackdocstheme
> with PDF theme & styles.

LGTM. I did notice that there are no OpenStack logos on the Install Guides, though. Is this deliberate?

> Also, since I am not familiar with the following issues, please also share your idea & thoughts on:
>  - In conf.py, version numbers are specified such as "0.0.1" and "0.9".
>    Will it be so important for PDFs? I think just "master" or release names such as "Newton" and "Ocata"
>    would deliver more contextual meanings to document readers.

Release names would be best, if you can do it.

>  - I suggest not to use chapter and section numbers for PDFs.
>    Current rst documents are written for the best presentation with HTMLs but current chapter and section
>    notations prevent PDFs from automatically parsing appropriate numbers. For example, [2-4] denote
>    number "1" for "Abstract", "3" for "Appendix", and so on.
>  - Could somebody recommend to select open source font(s) suitable to the PDFs?

The 'Liberation' family is often a good choice: https://fedorahosted.org/liberation-fonts/


Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 538 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20170206/c927390c/attachment.pgp>

More information about the OpenStack-docs mailing list