Open Stack

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.

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


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-openstack-manuals-tox-doc-publish-checkbuild/d8ffd03//publish-docs/
[9] https://etherpad.openstack.org/p/docs-build-pdf-from-rst-styling