<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On 9 February 2017 at 00:06, Ian Y. Choi <span dir="ltr"><<a href="mailto:ianyrchoi@gmail.com" target="_blank">ianyrchoi@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div bgcolor="#FFFFFF">
<div class="gmail-m_-3557704340050434214moz-cite-prefix">Oops.. I forgot one more thing:<br>
<br>
One thing I have not found yet the solution is that <br>
all install-guides (install-guide-debian, install-guide-obs,
install-guide-rdo, install-guide-ubuntu)<br>
use the same title "Install Guide".<br>
<br>
It is because they share the same conf.py on some variables<br>
(might be "pdf_documents").<br>
<br>
Tool teams, would it be possible to use different values on
conf.py variables<br>
for different install guides using the same conf.py?<br>
I need your help :)<br>
<br></div></div></blockquote><div><br></div><div>I believe the answer is yes. Because conf.py is a Python file, it can include conditional statements. For example:<br><br></div><div>if distro = 'Ubuntu':<br></div><div> pdf_documents = [<br> ('index', u'UbuntuInstallGuide', u'Ubuntu Install Guide',<br> u'OpenStack contributors')<br> ]<br></div><div>elif distro = 'RDO':<br> ...<br><br></div><div>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.<br><br></div><div>Let me know if you'd like some help and we can discuss off the mailing list. :)<br><br></div><div>Cheers,<br><br></div><div>Brian<br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF"><div class="gmail-m_-3557704340050434214moz-cite-prefix">
<br>
With many thanks,<br>
<br>
/Ian<div><div class="gmail-h5"><br>
<br>
Ian Y. Choi wrote on 2/8/2017 11:01 PM:<br>
</div></div></div><div><div class="gmail-h5">
<blockquote type="cite">
<div class="gmail-m_-3557704340050434214moz-cite-prefix">Thanks all for kind comments!<br>
<br>
Now I have divided into three different groups to complete the
spec in Ocata cycle:<br>
<br>
1. Moving current proposed LaTeX style to openstackdocstheme<br>
: <a class="gmail-m_-3557704340050434214moz-txt-link-freetext" href="https://review.openstack.org/#/c/430263/" target="_blank">https://review.openstack.org/#<wbr>/c/430263/</a><br>
<br>
- After then, releasing a new version for openstackdocstheme
might be needed to apply into the third group.<br>
<br>
2. Using Liberation font as English PDF documents<br>
: <a class="gmail-m_-3557704340050434214moz-txt-link-freetext" href="https://review.openstack.org/#/c/430549/" target="_blank">https://review.openstack.org/#<wbr>/c/430549/</a><br>
<br>
- I have seen
<a class="gmail-m_-3557704340050434214moz-txt-link-freetext" href="http://git.openstack.org/cgit/openstack/clouddocs-maven-plugin/log/src/main/resources/fonts" target="_blank">http://git.openstack.org/cgit/<wbr>openstack/clouddocs-maven-<wbr>plugin/log/src/main/resources/<wbr>fonts</a><br>
, but there is no information why CartoGothic font was
selected on there.<br>
IMO configuring different fonts for translated PDFs would be
possible, but I would like to<br>
implement this as a next step, since there might be some more
consideration to fully implement this.<br>
(Writing a new spec for Pike cycle would be a good idea I
think.)<br>
<br>
3. Applying LaTeX style using openstackdocstheme<br>
: <a class="gmail-m_-3557704340050434214moz-txt-link-freetext" href="https://review.openstack.org/#/c/427826/" target="_blank">https://review.openstack.org/#<wbr>/c/427826/</a>
will be adjusted after merging the first patch.<br>
<br>
- Current is WIP and I think it would be nice to remove WIP
after the new version of openstackdocstheme will be released<br>
and the patch will make use of the new version of
openstackdocstheme.<br>
- Some (e.g., a few cases for too many characters in a line)
might be enhanced by patching on the 1st group,<br>
while others would be enhanced by adding more concise
directives in each rst document<br>
(e.g., tabularcolumns directive).<br>
<br>
The patches in three groups are somewhat inter-related, and also
reviewing them<br>
with different perspectives like tooling, styling, and UXs would
make PDF implementation more flawless :)<br>
<br>
<br>
Anne Gentle wrote on 2/7/2017 11:31 PM:<br>
</div>
<blockquote type="cite">
<div dir="ltr"><br>
<div class="gmail_extra"><br>
<div class="gmail_quote">On Sun, Feb 5, 2017 at 4:54 PM, Ian
Y. Choi <span dir="ltr"><<a href="mailto:ianyrchoi@gmail.com" target="_blank">ianyrchoi@gmail.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hello,<br>
<br>
Me and SeongSoo have been collaborating a lot to apply
better customized styles<br>
to PDF documents from rst-based guide documents (spec is
available at [1]).<br>
<br>
Applying styles from documents with a basic pdflatex
theme (example: [2, 3, 4]) have not been easy for us.<br>
However, thanks to the new sphinx version support [5],
lots of latest styling options described<br>
in Sphinx documentation [6] are now well-applicable to
openstack-manuals!<br>
<br>
The draft PDF styling results are available at [7].<br>
You can check new PDF files by clicking
"gate-openstack-manuals-tox-do<wbr>c-publish-checkbuild"<br>
and "(pdf)" links for arch-design, ha-guide,
image-guide, and user-guide (for example: [8]).<br>
<br>
More detailed descriptions are available at Etherpad
[9].<br>
<br>
I would like to ask team members to review the new draft
PDF styling results,<br>
and if you are fine, then me and SeongSoo want to
migrate current python and latex styling files<br>
into openstackdocstheme and then polish [7] to make use
of a new openstackdocstheme<br>
with PDF theme & styles.<br>
<br>
Also, since I am not familiar with the following issues,
please also share your idea & thoughts on:<br>
- In conf.py, version numbers are specified such as
"0.0.1" and "0.9".<br>
Will it be so important for PDFs? I think just
"master" or release names such as "Newton" and "Ocata"<br>
</blockquote>
<div><br>
</div>
<div>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.</div>
</div>
</div>
</div>
</blockquote>
<br>
+1<br>
I have thought just for install-guides and network-guides, but
yes, the implementation method can be easily extended<br>
to api-site and client guides. Fortunately, the variation can be
accomplished easily by just changing "version" variable in
conf.py!<br>
<br>
<blockquote type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<div> </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> would deliver
more contextual meanings to document readers.<br>
- I suggest not to use chapter and section numbers for
PDFs.<br>
Current rst documents are written for the best
presentation with HTMLs but current chapter and section<br>
notations prevent PDFs from automatically parsing
appropriate numbers. For example, [2-4] denote<br>
number "1" for "Abstract", "3" for "Appendix", and so
on.<br>
</blockquote>
<div><br>
</div>
<div>I think that's fine. Page numbers are sufficient as
is anything the parser gives us now.</div>
<div> </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> - Could somebody
recommend to select open source font(s) suitable to the
PDFs?<br>
<br>
<br>
</blockquote>
<div><br>
</div>
<div>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 <span style="font-size:12.8px">CartoGothic-Std for the
English font. For Japanese it was </span><span style="font-size:12.8px">TakaoGothic </span><span class="gmail-m_-3557704340050434214gmail-il" style="font-size:12.8px;background-color:rgb(255,255,255)">font.
The thread with a lot of info is here: <a href="http://lists.openstack.org/pipermail/openstack-docs/2013-May/001583.html" target="_blank">http://lists.openstack.<wbr>org/pipermail/openstack-docs/<wbr>2013-May/001583.html</a></span></div>
<div><span class="gmail-m_-3557704340050434214gmail-il" style="font-size:12.8px;background-color:rgb(255,255,255)"><br>
</span></div>
<div><span class="gmail-m_-3557704340050434214gmail-il" style="font-size:12.8px;background-color:rgb(255,255,255)">Nice
work Ian, much appreciated.</span></div>
<div><span class="gmail-m_-3557704340050434214gmail-il" style="font-size:12.8px;background-color:rgb(255,255,255)">Anne</span></div>
<div> </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> With many thanks,<br>
<br>
/Ian<br>
<br>
[1] <a href="http://specs.openstack.org/openstack/docs-specs/specs/ocata/build-pdf-from-rst-guides.html" rel="noreferrer" target="_blank">http://specs.openstack.org/ope<wbr>nstack/docs-specs/specs/ocata/<wbr>build-pdf-from-rst-guides.html</a><br>
[2] <a href="http://docs.openstack.org/arch-design/ArchGuideRst.pdf" rel="noreferrer" target="_blank">http://docs.openstack.org/arch<wbr>-design/ArchGuideRst.pdf</a><br>
[3] <a href="http://docs.openstack.org/ha-guide/HAGuide.pdf" rel="noreferrer" target="_blank">http://docs.openstack.org/ha-g<wbr>uide/HAGuide.pdf</a><br>
[4] <a href="http://docs.openstack.org/draft/install-guide-ubuntu/InstallGuide.pdf" rel="noreferrer" target="_blank">http://docs.openstack.org/draf<wbr>t/install-guide-ubuntu/Install<wbr>Guide.pdf</a><br>
[5] <a href="https://review.openstack.org/#/c/419110/2/test-requirements.txt" rel="noreferrer" target="_blank">https://review.openstack.org/#<wbr>/c/419110/2/test-requirements.<wbr>txt</a><br>
[6] <a href="http://www.sphinx-doc.org/en/stable/latex.html" rel="noreferrer" target="_blank">http://www.sphinx-doc.org/en/s<wbr>table/latex.html</a><br>
[7] <a href="https://review.openstack.org/#/c/427826/" rel="noreferrer" target="_blank">https://review.openstack.org/#<wbr>/c/427826/</a><br>
[8] <a href="http://docs-draft.openstack.org/26/427826/13/check/gate-openstack-manuals-tox-doc-publish-checkbuild/d8ffd03//publish-docs/" rel="noreferrer" target="_blank">http://docs-draft.openstack.or<wbr>g/26/427826/13/check/gate-open<wbr>stack-manuals-tox-doc-publish-<wbr>checkbuild/d8ffd03//publish-do<wbr>cs/</a><br>
[9] <a href="https://etherpad.openstack.org/p/docs-build-pdf-from-rst-styling" rel="noreferrer" target="_blank">https://etherpad.openstack.org<wbr>/p/docs-build-pdf-from-rst-sty<wbr>ling</a><br>
<br>
______________________________<wbr>_________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.openstack<wbr>.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi<wbr>-bin/mailman/listinfo/openstac<wbr>k-docs</a><br>
</blockquote>
</div>
<br>
<br clear="all">
<div><br>
</div>
-- <br>
<div class="gmail-m_-3557704340050434214gmail-m_-4310550665490738873gmail-m_3597669042479164930gmail_signature">
<div dir="ltr">
<div>
<div dir="ltr">
<div dir="ltr">
<div dir="ltr">
<div><br>
</div>
<div>Read my blog: <a href="https://justwriteclick.com" target="_blank">justwrite.click</a></div>
<div>Subscribe to Docs|Code: <a href="http://docslikecode.com" target="_blank">docslikecode.com</a> </div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</blockquote>
<p><br>
</p>
</blockquote>
<p><br>
</p>
</div></div></div>
<br>______________________________<wbr>_________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.<wbr>openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-docs</a><br>
<br></blockquote></div><br></div></div>