writing a book using sphinx #sphinxconjp 2012
DESCRIPTION
Japanese version. http://www.slideshare.net/shimizukawa/sphinx-pyconjp-2012 I will introduce the procedure and its benefits, such as when the book was written from the experience of translation and my past two books, to automate the writing environment to leverage the Sphinx. Video of the announcement is here: http://www.youtube.com/watch?v=7VOJpFHnPWgTRANSCRIPT
Writing a Book Using Sphinx
2012/9/16SphinxCon JP 2012
Presentation detail is here
http://清水川.jp/ @shimizukawa
● BeProud Corp.● Expert Python Programming
translator into Japanese● Sphinx-users.jp vice-chairman● PyConJP 2011,2012 vice-chairman
Who am I?
● Publisher: Shuwa System● Size: B5, 430 pages● 2940 JPY● 2012-3-27
call it #pypro
Python Professional Programming
Our editor has sold the #pypro on PyConJP. However, many people had already purchased.
Fortunately, a lot of selling
● BPStyle (BeProud style):The book tell BP has been cultivated in the practice, the know-how of Python at work.
● for BP newbe:The book for work early to get accustomed to the new members of the company.
Book's concept
4 parts, 15 chapters
1. Let's develop with Python2. Cycle of team development3. Publish service4. Technique to accelerate the development
Table of Contents
Chapter 1: Let's start PythonChapter 2: Create a Web application
Appendix A: VirtualBox setupAppendix B: OS(Ubuntu) setup
Part 1: Let's develop with Python
Chapter 3: Create an environment of team developmentChapter 4: Prepare the foundation for documentChapter 5: Review and issue managementChapter 6: Design of module division and unit testingChapter 7: Automated packaging and environment setupChapter 8: Source Code Management with MercurialChapter 9: Continuous Integration with Jenkins
Part 2: Cycle of team development
Chapter 10: Automated environment to build and deployChapter 11: Improve the performance of applicationsChapter 12: Google App Engine
Chapter 13: Test is our friendChapter 14: Use Django to convenientlyChapter 15: To use the handy Python module
Part 3: Publish service
Part 4: Technique to accelerate the development
1. tell-k: Chap 1,12, Appendix A, B
2. Okano: Chap 2,8,11,153. aita: Chap 34. Shimizukawa: Chap 4,75. Imagawa Yakata: Chap
5,96. Azuma: Chap 5,107. Tomita: Chap 5
Authors
8. (aodag): Chap 69. monjudoh: Chap 8
10. cactusman: Chap 9
11. drillbits: Chap 1,1212. natsu: Chap 1313. Ikeda: Chap 1414. Hata: Chap 14
● Sphinx = Documentation toolhttp://sphinx-users.jp/
PyPro book was written by Sphinx
First:$ hg clone [repos-of-pypro] pypro$ cd pypro$ python bootstrap.py$ bin/buildout
build HTML:$ vim 04.rst #chapter 04$ make html
Build a writing environment automatically using Sphinx
Convert process of Sphinx
reST(reStrucutrdText)
docutils node tree
HTML
Docutils parser
Sphinx HTML writer
● Write by reST● HTML Review by office-member● PDF Review by outer-geeks
Provide different formats for different purposes.
If you change the look, we now notice that such wrong or strange expression that was not noticed until then.
Writing and Review
process: Writer -> Editor -> Print● [Editor -> Print]
maybe 'InDesign' or else.
● [Writer -> Editor]the Shuwa-System format.
Submission format for Editor
■■■■■Chapter 1 Let's start Python
▽◆・Python setup・Mercurial setup△◆
■■■■01-01 Python setup
5 wide square charactors ->
2 wide charactors ->
2 wide charactors ->
4 wide square charactors ->
1 wide bullet charactor ->
1 wide bullet charactor ->
● We wrote draft with Sphinx(reST)
● Submission format is different
● But, we can't write submission format. It's difficult for us :(
● Then, ...how?
Rewrite manually for submission?
● Shuwa-builder generate shuwa-system submission format from sphinx.
I created Shuwa-Builder for Sphinx
Shuwa-System
Generate submission formatted manuscript for Shuwa-System:
$ make shuwa
That's all.
$ ls _build/shuwa01.txt 02.txt 03.txt 04.txt ....
Generate manuscript for Shuwa
● I took a lot of time to create the bulider.● But monotonous repetitive work is painful
to me.● I will submit several times until publication.
I will get a return on that investment.
shortly afterward, I applying proved difference to original reST draft :(
3rd proof paper was PDF format. How do I check diff?
Spent over 2 days to create the Shuwa-builder
What went wrong● auto-generation of submission manuscript needs
explicit spec.● consider how to diff-incorporation
What worked● Written in text that easy to writing and manage
differential● Review need differencial look● To automate the preparation of environmental● At any time to provide the latest HTML and PDF
○ that is provided by Jenkins at commit&push to the repository.
Conclusion