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

Anne Gentle annegentle at justwriteclick.com
Tue Feb 7 14:31:28 UTC 2017

On Sun, Feb 5, 2017 at 4:54 PM, Ian Y. Choi <ianyrchoi at gmail.com> 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-do
> c-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.
> 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"

Depends on the type of guide. For admin guides and other openstack-manuals
guides, the grouped release name is sufficient. However, for Client guides
like python-openstackclient, that version number is crucial for bug
reporting and what features are available in a release. If your PDF
generation scope is for openstack-manuals, release names are fine. For
number-relevant releases, please ensure the release number is used.

>    would deliver more contextual meanings to document readers.
>  - 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.

I think that's fine. Page numbers are sufficient as is anything the parser
gives us now.

>  - Could somebody recommend to select open source font(s) suitable to the
> PDFs?
I looked up the history and we had to choose open source fonts per language
output. So test the font with translated docs also. We used to use
for the English font. For Japanese it was TakaoGothic font. The thread with
a lot of info is here:

Nice work Ian, much appreciated.

> With many thanks,
> /Ian
> [1] http://specs.openstack.org/openstack/docs-specs/specs/ocata/
> build-pdf-from-rst-guides.html
> [2] http://docs.openstack.org/arch-design/ArchGuideRst.pdf
> [3] http://docs.openstack.org/ha-guide/HAGuide.pdf
> [4] http://docs.openstack.org/draft/install-guide-ubuntu/InstallGuide.pdf
> [5] https://review.openstack.org/#/c/419110/2/test-requirements.txt
> [6] http://www.sphinx-doc.org/en/stable/latex.html
> [7] https://review.openstack.org/#/c/427826/
> [8] http://docs-draft.openstack.org/26/427826/13/check/gate-open
> stack-manuals-tox-doc-publish-checkbuild/d8ffd03//publish-docs/
> [9] https://etherpad.openstack.org/p/docs-build-pdf-from-rst-styling
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


Read my blog: justwrite.click <https://justwriteclick.com>
Subscribe to Docs|Code: docslikecode.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20170207/1abf9244/attachment.html>

More information about the OpenStack-docs mailing list