Open Stack

On 9 February 2017 at 00:06, Ian Y. Choi <ianyrchoi at gmail.com> wrote:

> 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 :)
>
>
I believe the answer is yes. Because conf.py is a Python file, it can
include conditional statements. For example:

if distro = 'Ubuntu':
    pdf_documents = [
        ('index', u'UbuntuInstallGuide', u'Ubuntu Install Guide',
        u'OpenStack contributors')
    ]
elif distro = 'RDO':
    ...

The trick is determining which guide is being built each time conf.py is
read. I suspect there should be an environment variable available that can
help.

Let me know if you'd like some help and we can discuss off the mailing
list. :)

Cheers,

Brian



>
> 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> 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.
>
>
> +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
>> [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
>
>
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20170213/53580240/attachment-0001.html>