Open Stack

Thanks all for kind comments!

Now I have divided into three different groups to complete the spec in 
Ocata cycle:

1. Moving current proposed LaTeX style to openstackdocstheme
  : https://review.openstack.org/#/c/430263/

- After then, releasing a new version for openstackdocstheme might be 
needed to apply into the third group.

2. Using Liberation font as English PDF documents
  : https://review.openstack.org/#/c/430549/

- I have seen 
http://git.openstack.org/cgit/openstack/clouddocs-maven-plugin/log/src/main/resources/fonts
   , but there is no information why CartoGothic font was selected on there.
   IMO configuring different fonts for translated PDFs would be 
possible, but I would like to
   implement this as a next step, since there might be some more 
consideration to fully implement this.
   (Writing a new spec for Pike cycle would be a good idea I think.)

3. Applying LaTeX style using openstackdocstheme
  : https://review.openstack.org/#/c/427826/ will be adjusted after 
merging the first patch.

- Current is WIP and I think it would be nice to remove WIP after the 
new version of openstackdocstheme will be released
   and the patch will make use of the new version of openstackdocstheme.
- Some (e.g., a few cases for too many characters in a line) might be 
enhanced by patching on the 1st group,
   while others would be enhanced by adding more concise directives in 
each rst document
   (e.g., tabularcolumns directive).

The patches in three groups are somewhat inter-related, and also 
reviewing them
with different perspectives like tooling, styling, and UXs would make 
PDF implementation more flawless :)


Anne Gentle wrote on 2/7/2017 11:31 PM:
>
>
> On Sun, Feb 5, 2017 at 4:54 PM, Ian Y. Choi <ianyrchoi at gmail.com 
> <mailto: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-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"
>
>
> 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.

+1
I have thought just for install-guides and network-guides, but yes, the 
implementation method can be easily extended
to api-site and client guides. Fortunately, the variation can be 
accomplished easily by just changing "version" variable in conf.py!

>        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
>     <http://specs.openstack.org/openstack/docs-specs/specs/ocata/build-pdf-from-rst-guides.html>
>     [2] http://docs.openstack.org/arch-design/ArchGuideRst.pdf
>     <http://docs.openstack.org/arch-design/ArchGuideRst.pdf>
>     [3] http://docs.openstack.org/ha-guide/HAGuide.pdf
>     <http://docs.openstack.org/ha-guide/HAGuide.pdf>
>     [4]
>     http://docs.openstack.org/draft/install-guide-ubuntu/InstallGuide.pdf
>     <http://docs.openstack.org/draft/install-guide-ubuntu/InstallGuide.pdf>
>     [5]
>     https://review.openstack.org/#/c/419110/2/test-requirements.txt
>     <https://review.openstack.org/#/c/419110/2/test-requirements.txt>
>     [6] http://www.sphinx-doc.org/en/stable/latex.html
>     <http://www.sphinx-doc.org/en/stable/latex.html>
>     [7] https://review.openstack.org/#/c/427826/
>     <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/
>     <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
>     <https://etherpad.openstack.org/p/docs-build-pdf-from-rst-styling>
>
>     _______________________________________________
>     OpenStack-docs mailing list
>     OpenStack-docs at lists.openstack.org
>     <mailto:OpenStack-docs at lists.openstack.org>
>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>     <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs>
>
>
>
>
> -- 
>
> Read my blog: justwrite.click <https://justwriteclick.com>
> Subscribe to Docs|Code: docslikecode.com <http://docslikecode.com>


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20170208/a8787abe/attachment.html>