http://sphinx-users.jp/event/20101203_jus_benkyoukai.html 日本UNIXユーザ会 2010年12月勉強会 (2010/12/3) 日本UNIXユーザ会の2010年12月の勉強会にて、以下の内容で発表させていただきました。 「ドキュメントを作りたくなってしまう魔法のツール Sphinx」

1. UNIX
2010 12
Sphinx-­‐users.jp

2. 

id
:
ymotongpoo

 OSS
 Tornado
Web
 Redis
KVS
 Jinja2

3. Twitter:
@shibukawa

 SE


 SphinxUsers.jp

 XP
 Ruby
 Python ( )
 11/14 Python
Hack-­‐a-­‐thon

 IT
( )
 Python
(

( R&D)
:
web

4. http:// .jp/
@shimizukawa
 :
 Sphinx-­‐users.jp
 Zope/Plone
 ,
pyspa ,
XP
 :
 Python,
Rails,
C++/C/8086
 :
 Python/Rails

 Python

 B5
416

6. 3


7. 
 100%
 sphinx-­‐user.jp



http://sphinx-­‐users.jp/example.html

http://sphinx.pocoo.org/examples.html

9. 
1. Sphinx
2. Sphinx
3. reST
4. Sphinx




10. 1/4
Sphinx
 2

 Python,
easy_install,
Sphinx 3

 Ubuntu
$
sudo
apt-­‐get
install
python-­‐sphinx
 Mac
OS
X
$
sudo
port
install
python-­‐sphinx


11. 2/4
Sphinx
 “sphinx-­‐quickstart”
$
mkdir
Unix-­‐How-­‐to
$
cd
Unix-­‐How-­‐to
$
sphinx-­‐quickstart
 Enter
.
 conf.py
 3




12. 3/4
reST
 reST
=
reStructuredText
 http://sphinx-­‐users.jp/doc10/rest.html
============

============


=========


-­‐-­‐-­‐-­‐-­‐-­‐-­‐-­‐-­‐-­‐-­‐-­‐-­‐
-­‐ 1
 toctree
-­‐ 2
#.
1
#.
2

13. 4/4
Sphinx
 Makefile
$
make
html
============
============
=========
1
2
-­‐ 1
1.
1
-­‐ 2
2.
2
#.
1
#.
2

14. 1/2
 HTML LaTeX PDF
ePub
$
make
latex
$
make
latexpdf
$
make
epub
 HTML

15. 
“Jinja2”
 2 html

:
layout.html

:
page.html

basic

16. Sphinx
 OSS
 Python
2.6.2
 OpenPNE
Web
API
 groonga …


17. Sphinx
 Sphinx
 Python &
(Erlang,
Ruby,
C++,
JavaScript…)

)
C
c:function::
int
printf(const
char
*format,
…)
..

18. Sphinx



 Sphinx

19. Sphinx
 autodoc
–
docstring
 intersphinx
–
Sphinx
 pngmath
–
PNG
 jsmath
–
JavaScript
 graphviz
–
Graphviz
 coverage
–
 todo
–
Todo
Sphinx

20. Sphinx

 sdedit
 UML
 blockdiag

 docx
 Sphinx Word

21. sdedit
(Quick
Sequence
Deiagram
Editor)
 UML
..
sequence-­‐diagram::
:maxwidth:
500
:linewrap:
false
:threadnumber:
true
actor:Actor
sphinx:Sphinx[a]
dot:Graphviz
sdedit:Quick
Sequence
Diagram
Editor
actor:sphinx.make
html
sphinx:dot.render_diagram()
sphinx:sdedit.render_diagram()

22. blockdiag
by
@tk0miya

 sphinxcontrib-­‐blockdiag
Sphinx
..
blockdiag::
diagram
webapp
{
login
-­‐>
something
-­‐>
logout
-­‐>
login
}

23. docx
 Sphinx Word

by

24.  Sphinx








26.

 Word

 OpenOffice
Writer
Microsoft Office

27.

 Excel
 Calc
Microsoft Office

28.

 PowerPoint
 KeyNote
 OpenOffice
Impress

29.

 Wiki
 HTML
 TeX

30. http://www.flickr.com/photos/boothy/26461481/
http://www.flickr.com/photos/omeyamapyonta/
CC
BY-­‐NC
by
Dr
Snafu
3052096093/
CC
BY-­‐SA
by
PYONKO
Word
Excel
Wiki
Sphinx
http://www.flickr.com/photos/johncarleton/2367673332/
http://www.flickr.com/photos/stompy/11300916/
CC
BY-­‐
CC
BY-­‐NC-­‐SA
by
John
Carleton
NC
by
Abizern

31. Word
-­‐
pros




etc…
http://www.flickr.com/photos/jetalone/861945664/
CC
BY
by
jetalone

32. Word
-­‐
cons
 1



http://www.flickr.com/photos/jetalone/861945664/
CC
BY
by
jetalone

33. Excel
-­‐
pros
 Excel


http://www.flickr.com/photos/
21183810@N00/4366518191/
CC
BY-­‐NC-­‐SA
by
Jerome
Rothermund

34. Excel
-­‐
cons


http://www.flickr.com/photos/
21183810@N00/4366518191/
CC
BY-­‐NC-­‐SA
by
Jerome
Rothermund

35. Wiki
-­‐
pros



http://www.flickr.com/photos/
7506006@N07/1197395511/
CC
BY-­‐NC-­‐ND
by
milky.way

36. Wiki
-­‐
cons

 Wikipedia


http://www.flickr.com/photos/
7506006@N07/1197395511/
CC
BY-­‐NC-­‐ND
by
milky.way

37. Sphinx
-­‐
pros



 OK
http://www.flickr.com/photos/
18261299@N00/4472408386/
CC
BY-­‐SA
by
sweet_redbird

38. Sphinx
-­‐
cons


 WYSIWIG
http://www.flickr.com/photos/
18261299@N00/4472408386/
CC
BY-­‐SA
by
sweet_redbird

40. 
 toctree toctree toctree



41. 
 #,
*,
=,
-­‐,
^,
~,
“

 H1,
H2,
H3..


42.  Sphinx
 toctree












43. 
 toctree 1
 toctree
toctree Sphinx

45. 

46. 
•
• + (UNIX )
• ( )
•

48.  ( )

..
_ :
:ref:` `
..
module::
:mod:` `
..
function::
:func:` `
..
class::
:class:` `
..
method::
:meth:` `
..
attr::
:attr:` `
berrymq.talk ( )!
"

49. 






50.
•
•

52. 40%
60%

53.











54. ω `)

56.  






..

57. 1.
2.
3.
4.

60. 7
1.
2.
3.
4.
5.
6.
7.
Python 10
10 :

61.
APPENDIX

62. 



63. 3 JUS

64. Step1
Sphinx
C:>
sphinx-­‐quickstart

65. Step2


66. Step3


67. Step4

70. Python

73. XP 2010
http:// .jp/docs/xpfest2010/

75. Python 10
10 :

76. 1.

2.

3.

4.


77. (´ ω `)