Open Stack

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
CartoGothic-Std
for the English font. For Japanese it was TakaoGothic font. The thread with
a lot of info is here:
http://lists.openstack.org/pipermail/openstack-docs/2013-May/001583.html

Nice work Ian, much appreciated.
Anne


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