Open Stack

Oops.. I forgot one more thing:

One thing I have not found yet the solution is that
all install-guides (install-guide-debian, install-guide-obs, 
install-guide-rdo, install-guide-ubuntu)
use the same title "Install Guide".

It is because they share the same conf.py on some variables
(might be "pdf_documents").

Tool teams, would it be possible to use different values on conf.py 
variables
for different install guides using the same conf.py?
I need your help :)


With many thanks,

/Ian

Ian Y. Choi wrote on 2/8/2017 11:01 PM:
> 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/df0a0ba9/attachment-0001.html>