Presentation detail is hereWriting a BookUsing Sphinx 2012/9/16SphinxCon JP 2012
Who am I?http://清水川.jp/ @shimizukawa● BeProud Corp.● Expert Python Programming translator into Japanese● Sphinx-users.jp vice-chairman● PyConJP 2011,2012 vice-chairman
Python Professional Programming● Publisher: Shuwa System● Size: B5, 430 pages● 2940 JPY● 2012-3-27call it #pypro
Fortunately, a lot of sellingOur editor has sold the #pypro on PyConJP.However, many people had alreadypurchased.
Books concept● 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.
Table of Contents4 parts, 15 chapters1. Lets develop with Python2. Cycle of team development3. Publish service4. Technique to accelerate the development
Part 1: Lets develop with PythonChapter 1: Lets start PythonChapter 2: Create a Web applicationAppendix A: VirtualBox setupAppendix B: OS(Ubuntu) setup
Part 2: Cycle of team developmentChapter 3: Create an environment of teamdevelopmentChapter 4: Prepare the foundation for documentChapter 5: Review and issue managementChapter 6: Design of module division and unittestingChapter 7: Automated packaging and environmentsetupChapter 8: Source Code Management withMercurialChapter 9: Continuous Integration with Jenkins
Part 3: Publish serviceChapter 10: Automated environment to build and deployChapter 11: Improve the performance of applicationsChapter 12: Google App EnginePart 4: Technique to accelerate thedevelopmentChapter 13: Test is our friendChapter 14: Use Django to convenientlyChapter 15: To use the handy Python module
Authors1. tell-k: Chap 1,12, Appendix A, B2. Okano: Chap 2,8,11,153. aita: Chap 3 8. (aodag): Chap 64. Shimizukawa: Chap 4,7 9. monjudoh: Chap 85. Imagawa Yakata: Chap 10. cactusman: Chap 5,9 96. Azuma: Chap 5,10 11. drillbits: Chap 1,127. Tomita: Chap 5 12. natsu: Chap 13 13. Ikeda: Chap 14 14. Hata: Chap 14
PyPro book was written by Sphinx● Sphinx = Documentation tool http://sphinx-users.jp/
Build a writing environmentautomatically using SphinxFirst: $ hg clone [repos-of-pypro] pypro $ cd pypro $ python bootstrap.py $ bin/buildoutbuild HTML: $ vim 04.rst #chapter 04 $ make html
Convert process of Sphinx reST(reStrucutrdText) Docutils parser docutils node tree Sphinx HTML writer HTML
Writing and Review● Write by reST● HTML Review by office-member● PDF Review by outer-geeksProvide different formats for differentpurposes.If you change the look, we now notice thatsuch wrong or strange expression that wasnot noticed until then.
Rewrite manually for submission?● We wrote draft with Sphinx(reST)● Submission format is different● But, we cant write submission format. Its difficult for us :(● Then, ...how?
I created Shuwa-Builder for Sphinx● Shuwa-builder generate shuwa-system submission format from sphinx. Shuwa-System
Generate manuscript for ShuwaGenerate submission formatted manuscriptfor Shuwa-System: $ make shuwaThats all. $ ls _build/shuwa 01.txt 02.txt 03.txt 04.txt ....
Spent over 2 days to create theShuwa-builder● 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 proveddifference to original reST draft :(3rd proof paper was PDF format. How do Icheck diff?
ConclusionWhat went wrong● auto-generation of submission manuscript needs explicit spec.● consider how to diff-incorporationWhat 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.