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