SlideShare a Scribd company logo
1 of 73
Download to read offline
Takayuki Shimizukawa
Sphinx co-maintainer
Sphinx-users.jp
1
こんにちは
Kon-Nichi-Wa
2
Who am I
@shimizukawa
1. Sphinx co-maintainer
2. Sphinx-users.jp
3. PyCon JP committee
 BePROUD co, ltd.
3
http://pycon.jp/
4
5
Do you know
the docstring?
6
1. def dumps(obj, ensure_ascii=True):
2. """Serialize ``obj`` to a JSON formatted
``str``.
3. """
4.
5. ...
6. return ...
Line 2,3 is a docstring
You can see the string by "help(dumps)"
Docstring
7
Have you written
API docs
using docstrings?
8
What is the reason you do not write docstrings.
 I don't know what/where should I write.
 Are there some docstring format spec?
 It's not beneficial.
I'll tell you a good way to write the docstrings.
9
Goal of this session
 How to generate a doc from Python source
code.
 re-discovering the meaning of docstrings.
10
11
What is Sphinx?
12
Sphinx is a documentation generator
Sphinx generates doc as several output
formats from the reST text markup
Sphinx
reSTreSTreStructuredText
(reST) reST Parser
HTML Builder
ePub Builder
LaTeX Builder texlive
HTML
theme
Favorite Editor
The history of Sphinx (short ver.)
13
The father of
Sphinx
Too hard to
maintenance
~2007
Easy to write
Easy to maintenance
2007~
Sphinx Before and After
Before
 There was no standard ways to write documents
 Sometime, we need converting markups into other formats
After
 Generate multiple output format from single source
 Integrated html themes make read docs easier
 API references can be integrated into narrative docs
 Automated doc building and hosting by ReadTheDocs
14
Many docs are written by Sphinx
For examples
 Python libraries/tools:
Python, Sphinx, Flask, Jinja2, Django, Pyramid,
SQLAlchemy, Numpy, SciPy, scikit-learn,
pandas, fabric, ansible, awscli, …
 Non python libraries/tools:
Chef, CakePHP(2.x), MathJax, Selenium,
Varnish
15
Many docs are written by Sphinx
For examples
 Python libraries/tools:
Python, Sphinx, Flask, Jinja2, Django, Pyramid,
SQLAlchemy, Numpy, SciPy, scikit-learn,
pandas, fabric, ansible, awscli, …
 Non python libraries/tools:
Chef, CakePHP(2.x), MathJax, Selenium,
Varnish
16
Sphinx extensions (built-in)
Sphinx provides these extensions to support
automated API documentation.
 sphinx.ext.autodoc
 sphinx.ext.autosummary
 sphinx.ext.doctest
 sphinx.ext.coverage
Sphinx
reST Parser
HTML Builder
ePub Builder
LaTeX Builder
docutils
autosummary
autodoc
doctest
coverage
17
library code example
1. "utility functions"
2.
3. def dumps(obj, ensure_ascii=True):
4. """Serialize ``obj`` to a JSON formatted ``str``.
5. """
6. ...
deep_thought/utils.py
$ tree /path/to/your-code
+- deep_thought
| +- __init__.py
| +- api.py
| +- calc.py
| +- utils.py
+- setup.py
18
$ pip install sphinx
 Your code and sphinx should be in single
python environment.
 Python version is also important.
How to install Sphinx
19
$ cd /path/to/your-code
$ sphinx-quickstart doc -m
...
Project name: Deep thought
Author name(s): Mice
Project version: 0.7.5
...
...
Finished
 "-m" to generate minimal Makefile/make.bat
 -m is important to introduce this session easily.
How to start a Sphinx project
Keep pressing ENTER key
20
Create a doc directory
$ cd doc
$ make html
...
Build finished. The HTML pages are in _build/html.
"make html" command
generates html files into
_build/html.
make html once
21
Current files structure
$ tree /path/to/your-code
+- deep_thought
| +- __init__.py
| +- api.py
| +- calc.py
| +- utils.py
+- doc
| +- _build/
| | +- html/
| +- _static/
| +- _template/
| +- conf.py
| +- index.rst
| +- make.bat
| +- Makefile
+- setup.py
Scaffold files
Build output
Library files
22
23
$ tree /path/to/your-code
+- deep_thought
| +- __init__.py
| +- api.py
| +- calc.py
| +- utils.py
+- doc
| +- _build/
| | +- html/
| +- _static/
| +- _template/
| +- conf.py
| +- index.rst
| +- make.bat
| +- Makefile
+- setup.py
1. import os
2. import sys
3. sys.path.insert(0, os.path.abspath('..'))
4. extensions = [
5. 'sphinx.ext.autodoc',
6. ]
setup autodoc extension
doc/conf.py
24
Line-3: add your library path to
import them from Sphinx autodoc.
Line-5: add 'sphinx.ext.autodoc' to
use the extension.
Add automodule directive to your doc
1. Deep thought API
2. ================
3.
4. .. automodule:: deep_thought.utils
5. :members:
6.
1. "utility functions"
2.
3. def dumps(obj, ensure_ascii=True):
4. """Serialize ``obj`` to a JSON formatted ``str``.
5. """
6. ...
doc/index.rst
25
deep_thought/utils.py
Line-4: automodule directive import specified
module and inspect the module.
Line-5: :members: option will inspects all members
of module not only module docstring.
$ cd doc
$ make html
...
Build finished. The HTML pages are in _build/html.
make html
26
How does it work?
autodoc directive generates intermediate reST
internally:
1. Deep thought API
2. ================
3.
4. .. py:module:: deep_thought.utils
5.
6. utility functions
7.
8. .. py:function:: dumps(obj, ensure_ascii=True)
9. :module: deep_thought.utils
10.
11. Serialize ``obj`` to a JSON formatted :class:`str`.
doc/index.rst
Intermediate
reST
27
$ make html SPHINXOPTS=-vvv
...
...
[autodoc] output:
.. py:module:: deep_thought.utils
utility functions
.. py:function:: dumps(obj, ensure_ascii=True)
:module: deep_thought.utils
Serialize ``obj`` to a JSON formatted :class:`str`.
You can see the reST with -vvv option
28
Take care!
Sphinx autodoc import your code
to get docstrings.
It means autodoc will execute code
at module global level.
29
Danger code
1. import os
2.
3. def delete_world():
4. os.system('sudo rm -Rf /')
5.
6. delete_world() # will be executed at "make html"
danger.py
30
execution guard on import
1. import os
2.
3. def delete_world():
4. os.system('sudo rm -Rf /')
5.
6. delete_world() # will be executed at "make html"
danger.py
1. import os
2.
3. def delete_world():
4. os.system('sudo rm -Rf /')
5.
6. if __name__ == '__main__':
7. delete_world() # doesn't execute at "make html"
safer.py
Execution guard
31
execution guard on import
1. import os
2.
3. def delete_world():
4. os.system('sudo rm -Rf /')
5.
6. delete_world() # will be executed at "make html"
danger.py
1. import os
2.
3. def delete_world():
4. os.system('sudo rm -Rf /')
5.
6. if __name__ == '__main__':
7. delete_world() # doesn't execute at "make html"
safer.py
Execution guard
32
"Oh, I can't understand the type of arguments
and meanings even reading this!"
33
Lacking necessary information
1. def dumps(obj, ensure_ascii=True):
2. """Serialize ``obj`` to a JSON formatted
3. :class:`str`.
4.
5. :param dict obj: dict type object to serialize.
6. :param bool ensure_ascii: Default is True. If
7. False, all non-ASCII characters are not ...
8. :return: JSON formatted string
9. :rtype: str
10. """
 http://sphinx-doc.org/domains.html#info-field-lists
"info field lists" for arguments
deep_thought/utils.py
34
def dumps(obj, ensure_ascii=True):
"""Serialize ``obj`` to a JSON formatted :class:`str`.
:param dict obj: dict type object to serialize.
:param bool ensure_ascii: Default is True. If
False, all non-ASCII characters are not ...
:return: JSON formatted string
:rtype: str
"""
...
"info field lists" for arguments
deep_thought/utils.py
35
Cross-reference to functions
1. Examples
2. ==========
3.
4. This is a usage of :func:`deep_thought.utils.dumps`
blah blah blah. ...
examples.py
reference
(hyper link)
36
37
Code example in a docstring
1. def dumps(obj, ensure_ascii=True):
2. """Serialize ``obj`` to a JSON formatted
3. :class:`str`.
4.
5. For example:
6.
7. >>> from deep_thought.utils import dumps
8. >>> data = dict(spam=1, ham='egg')
9. >>> dumps(data)
10. '{spam: 1, ham: "egg"}'
11.
12. :param dict obj: dict type object to serialize.
13. :param bool ensure_ascii: Default is True. If
14. False, all non-ASCII characters are not ...
deep_thought/utils.py
38
doctest
block
You can copy & paste the red lines
from python interactive shell.
Syntax highlighted output
$ make html
...
rendered
doctest
block
39
 You can expect that developers will update code
examples when the interface is changed.
We expect ...
1. def dumps(obj, ensure_ascii=True):
2. """Serialize ``obj`` to a JSON formatted
3. :class:`str`.
4.
5. For example:
6.
7. >>> from deep_thought.utils import dumps
8. >>> data = dict(spam=1, ham='egg')
9. >>> dumps(data)
10. '{spam: 1, ham: "egg"}'
The code example is
very close from
implementation!!
deep_thought/utils.py
40
 ̄\_(ツ)_/ ̄
41
doctest builder
42
1. ...
2.
3. extensions = [
4. 'sphinx.ext.autodoc',
5. 'sphinx.ext.doctest',
6. ]
7.
 Line-5: add 'sphinx.ext.doctest' extension.
setup doctest extension
doc/conf.py
append
43
$ make doctest
...
Document: api
-------------
********************************************************
File "api.rst", line 11, in default
Failed example:
dumps(data)
Expected:
'{spam: 1, ham: "egg"}'
Got:
'to-be-implemented'
...
make: *** [doctest] Error 1
Result of "make doctest"
44
Result of doctest
45
Individual pages for each modules
api.html
calc.html
utils.html
46
1. deep_thought.utils
2. ===================
3. .. automodule:: deep_thought.utils
4. :members:
doc/deep_thought.utils.rst
1. deep_thought.utils
2. ===================
3. .. automodule:: deep_thought.utils
4. :members:
Add automodule directive to your doc
doc/deep_thought.utils.rst
1. deep_thought.calc
2. ==================
3. .. automodule:: deep_thought.calc
4. :members:
1. deep_thought.api
2. ==================
3. .. automodule:: deep_thought.api
4. :members:
doc/deep_thought.calc.rst
doc/deep_thought.api.rst
And many many reST files ... 47
 ̄\_(ツ)_/ ̄
48
autosummary extension
49
1. ...
2.
3. extensions = [
4. 'sphinx.ext.autodoc',
5. 'sphinx.ext.doctest',
6. 'sphinx.ext.autosummary',
7. ]
8. autodoc_default_flags = ['members']
9. autosummary_generate = True
10.
 Line-9: autosummary_generate = True
generates reST files what you will specify with
using autosummary directive.
setup autosummary extension
doc/conf.py
append
append
append
50
1. Deep thought API
2. ================
3.
4. .. autosummary::
5. :toctree: generated
6.
7. deep_thought.api
8. deep_thought.calc
9. deep_thought.utils
10.
Replace automodule with autosummary
doc/index.rst
$ make html
...
51
Output of autosummary
autosummary directive
become TOC for each
module pages.
52
53
1. def spam():
2. ...
3. return res
4.
5. def ham():
6. ...
7. return res
8.
9. def egg():
10. ...
11. return res
How to find undocumented funcs?
doc/nodoc.py
54
coverage extension
55
1. ...
2.
3. extensions = [
4. 'sphinx.ext.autodoc',
5. 'sphinx.ext.doctest',
6. 'sphinx.ext.autosummary',
7. 'sphinx.ext.coverage',
8. ]
9. autodoc_default_flags = ['members']
10. autosummary_generate = True
setup coverage extension
doc/conf.py
append
 Line-7: add 'sphinx.ext.coverage' extension.
56
make coverage and check the result
$ make coverage
...
Testing of coverage in the sources finished, look at the
results in _buildcoverage.
$ ls _build/coverage
c.txt python.txt undoc.pickle
1. Undocumented Python objects
2. ===========================
3. deep_thought.utils
4. ------------------
5. Functions:
6. * egg
_build/coverage/python.txt
This function doesn't have a doc!
57
CAUTION!
1. Undocumented Python objects
2. ===========================
3. deep_thought.utils
4. ------------------
5. Functions:
6. * egg
python.txt
$ make coverage
...
Testing of coverage in the sources finished, look at the
results in _buildcoverage.
$ ls _build/coverage
c.txt python.txt undoc.pickle
The command always return ZERO
coverage.xml is not exist
reST format for whom?
58
Let's make Pull-Request!
We are waiting for your contribution
to solve the problem.
(bow)
59
60
Why don't you write docstrings?
 I don't know what/where should I write.
 Let's write a description, arguments and doctest blocks
at the next line of function signature.
 Are there some docstring format spec?
 Yes, you can use "info field list" for argument spec and
you can use doctest block for code example.
 It's not beneficial.
 You can use autodoc, autosummary, doctest and
coverage to make it beneficial.
61
62
1. Options
63
Options for autodoc
 :members: blah
 To document just specified members. Empty is ALL.
 :undoc-members: ...
 To document members which doesn't have docstring.
 :private-members: ...
 To document private members which name starts with
underscore.
 :special-members: ...
 To document starts with underscore underscore.
 :inherited-members: ...
 To document inherited from super class.
64
2. Directives for Web API
sphinxcontrib-httpdomain
65
sphinxcontrib-httpdomain extension
http domain's get directive
render
page
render routing table (index)
http highlighter
It also contains sphinxcontrib.autohttp.flask, .bottle, .tornado extensions
Listing
New Index
66
3. Directives for Diagram
sphinxcontrib-blockdiag
sphinxcontrib-sqdiag
sphinxcontrib-actdiag
sphinxcontrib-nwdiag
67
blockdiag series
68
http://blockdiag.com/
blockdiag seqdiag (sequence)
actdiag (activity) nwdiag (network)
packetdiag (packet)
is included in nwdiag
class Request(object):
"""
.. seqdiag::
{
code [label="Your Code"];
lib [label="Library"];
site [label="Web Site"];
code -> lib [label="Request(url)"];
code <-- lib [label="req"];
code -> lib [label="req.open(auth_cb)"];
lib -> site [label="GET"];
lib <-- site [label="status=401"];
lib => code [label="auth_cb(realm)", ...
lib -> site [label="GET/auth header"];
lib <-- site [label="status=200"];
code <-- lib [label="status"];
}
"""
sphinxcontrib-seqdiag extension
69
deep_thought/api.py
extensions = [
'sphinxcontrib.seqdiag',
]
conf.py
$ pip install sphinxcontrib-seqdiag
4. Document translation
70
Translation into other languages
$ make gettext
...
Build finished. The message catalogs are in
_build/gettext.
$ sphinx-intl update -p _build/gettext -l es
#: ../../../deep_thought/utils.pydocstring of deep_thought.
msgid "Serialize ``obj`` to a JSON formatted :class:`str`."
msgstr "Serializar ``obj`` a un formato JSON :class:`str`."
msgid "For example:"
msgstr "Por ejemplo:"
locale/es/LC_MESSAGES/generated.po
language = 'es'
locale_dirs = ['locale']
conf.py
$ make html
...
Build finished. The HTML pages are in _build/html.
71
Questions?
@shimizukawa
Grab me after the session :)
72
Thanks :)
73

More Related Content

What's hot

Syncing up with Python’s asyncio for (micro) service development, Joir-dan Gumbs
Syncing up with Python’s asyncio for (micro) service development, Joir-dan GumbsSyncing up with Python’s asyncio for (micro) service development, Joir-dan Gumbs
Syncing up with Python’s asyncio for (micro) service development, Joir-dan GumbsPôle Systematic Paris-Region
 
閒聊Python應用在game server的開發
閒聊Python應用在game server的開發閒聊Python應用在game server的開發
閒聊Python應用在game server的開發Eric Chen
 
Py conkr 20150829_docker-python
Py conkr 20150829_docker-pythonPy conkr 20150829_docker-python
Py conkr 20150829_docker-pythonEric Ahn
 
Memory Management In Python The Basics
Memory Management In Python The BasicsMemory Management In Python The Basics
Memory Management In Python The BasicsNina Zakharenko
 
History & Practices for UniRx(EN)
History & Practices for UniRx(EN)History & Practices for UniRx(EN)
History & Practices for UniRx(EN)Yoshifumi Kawai
 
pyconjp2015_talk_Translation of Python Program__
pyconjp2015_talk_Translation of Python Program__pyconjp2015_talk_Translation of Python Program__
pyconjp2015_talk_Translation of Python Program__Renyuan Lyu
 
PyCon Taiwan 2013 Tutorial
PyCon Taiwan 2013 TutorialPyCon Taiwan 2013 Tutorial
PyCon Taiwan 2013 TutorialJustin Lin
 
Happy Go Programming Part 1
Happy Go Programming Part 1Happy Go Programming Part 1
Happy Go Programming Part 1Lin Yo-An
 
Easy contributable internationalization process with Sphinx @ PyCon APAC 2016
Easy contributable internationalization process with Sphinx @ PyCon APAC 2016Easy contributable internationalization process with Sphinx @ PyCon APAC 2016
Easy contributable internationalization process with Sphinx @ PyCon APAC 2016Takayuki Shimizukawa
 
Concurrency in Python
Concurrency in PythonConcurrency in Python
Concurrency in PythonMosky Liu
 
Introduction to Programming in Go
Introduction to Programming in GoIntroduction to Programming in Go
Introduction to Programming in GoAmr Hassan
 
これからのPerlプロダクトのかたち(YAPC::Asia 2013)
これからのPerlプロダクトのかたち(YAPC::Asia 2013)これからのPerlプロダクトのかたち(YAPC::Asia 2013)
これからのPerlプロダクトのかたち(YAPC::Asia 2013)goccy
 
服务框架: Thrift & PasteScript
服务框架: Thrift & PasteScript服务框架: Thrift & PasteScript
服务框架: Thrift & PasteScriptQiangning Hong
 
Php and threads ZTS
Php and threads ZTSPhp and threads ZTS
Php and threads ZTSjulien pauli
 
Minimal MVC in JavaScript
Minimal MVC in JavaScriptMinimal MVC in JavaScript
Minimal MVC in JavaScriptMosky Liu
 

What's hot (20)

Syncing up with Python’s asyncio for (micro) service development, Joir-dan Gumbs
Syncing up with Python’s asyncio for (micro) service development, Joir-dan GumbsSyncing up with Python’s asyncio for (micro) service development, Joir-dan Gumbs
Syncing up with Python’s asyncio for (micro) service development, Joir-dan Gumbs
 
閒聊Python應用在game server的開發
閒聊Python應用在game server的開發閒聊Python應用在game server的開發
閒聊Python應用在game server的開發
 
Py conkr 20150829_docker-python
Py conkr 20150829_docker-pythonPy conkr 20150829_docker-python
Py conkr 20150829_docker-python
 
Memory Management In Python The Basics
Memory Management In Python The BasicsMemory Management In Python The Basics
Memory Management In Python The Basics
 
Hacking with hhvm
Hacking with hhvmHacking with hhvm
Hacking with hhvm
 
History & Practices for UniRx(EN)
History & Practices for UniRx(EN)History & Practices for UniRx(EN)
History & Practices for UniRx(EN)
 
pyconjp2015_talk_Translation of Python Program__
pyconjp2015_talk_Translation of Python Program__pyconjp2015_talk_Translation of Python Program__
pyconjp2015_talk_Translation of Python Program__
 
PyCon Taiwan 2013 Tutorial
PyCon Taiwan 2013 TutorialPyCon Taiwan 2013 Tutorial
PyCon Taiwan 2013 Tutorial
 
Happy Go Programming Part 1
Happy Go Programming Part 1Happy Go Programming Part 1
Happy Go Programming Part 1
 
Python build your security tools.pdf
Python build your security tools.pdfPython build your security tools.pdf
Python build your security tools.pdf
 
Easy contributable internationalization process with Sphinx @ PyCon APAC 2016
Easy contributable internationalization process with Sphinx @ PyCon APAC 2016Easy contributable internationalization process with Sphinx @ PyCon APAC 2016
Easy contributable internationalization process with Sphinx @ PyCon APAC 2016
 
Concurrency in Python
Concurrency in PythonConcurrency in Python
Concurrency in Python
 
Introduction to Programming in Go
Introduction to Programming in GoIntroduction to Programming in Go
Introduction to Programming in Go
 
これからのPerlプロダクトのかたち(YAPC::Asia 2013)
これからのPerlプロダクトのかたち(YAPC::Asia 2013)これからのPerlプロダクトのかたち(YAPC::Asia 2013)
これからのPerlプロダクトのかたち(YAPC::Asia 2013)
 
服务框架: Thrift & PasteScript
服务框架: Thrift & PasteScript服务框架: Thrift & PasteScript
服务框架: Thrift & PasteScript
 
Php and threads ZTS
Php and threads ZTSPhp and threads ZTS
Php and threads ZTS
 
Minimal MVC in JavaScript
Minimal MVC in JavaScriptMinimal MVC in JavaScript
Minimal MVC in JavaScript
 
How do event loops work in Python?
How do event loops work in Python?How do event loops work in Python?
How do event loops work in Python?
 
Building Custom PHP Extensions
Building Custom PHP ExtensionsBuilding Custom PHP Extensions
Building Custom PHP Extensions
 
Pycon - Python for ethical hackers
Pycon - Python for ethical hackers Pycon - Python for ethical hackers
Pycon - Python for ethical hackers
 

Similar to Sphinx autodoc - automated api documentation - PyCon.MY 2015

Flask jwt authentication tutorial
Flask jwt authentication tutorialFlask jwt authentication tutorial
Flask jwt authentication tutorialKaty Slemon
 
Presentation of Python, Django, DockerStack
Presentation of Python, Django, DockerStackPresentation of Python, Django, DockerStack
Presentation of Python, Django, DockerStackDavid Sanchez
 
descriptive programming
descriptive programmingdescriptive programming
descriptive programmingAnand Dhana
 
Ts archiving
Ts   archivingTs   archiving
Ts archivingConfiz
 
Write better python code with these 10 tricks | by yong cui, ph.d. | aug, 202...
Write better python code with these 10 tricks | by yong cui, ph.d. | aug, 202...Write better python code with these 10 tricks | by yong cui, ph.d. | aug, 202...
Write better python code with these 10 tricks | by yong cui, ph.d. | aug, 202...amit kuraria
 
node.js, javascript and the future
node.js, javascript and the futurenode.js, javascript and the future
node.js, javascript and the futureJeff Miccolis
 
These questions will be a bit advanced level 2
These questions will be a bit advanced level 2These questions will be a bit advanced level 2
These questions will be a bit advanced level 2sadhana312471
 
Scripting as a Second Language
Scripting as a Second LanguageScripting as a Second Language
Scripting as a Second LanguageRob Dunn
 
Symfony finally swiped right on envvars
Symfony finally swiped right on envvarsSymfony finally swiped right on envvars
Symfony finally swiped right on envvarsSam Marley-Jarrett
 
Static code analysis: what? how? why?
Static code analysis: what? how? why?Static code analysis: what? how? why?
Static code analysis: what? how? why?Andrey Karpov
 
CoffeeScript Design Patterns
CoffeeScript Design PatternsCoffeeScript Design Patterns
CoffeeScript Design PatternsTrevorBurnham
 
A Check of the Open-Source Project WinSCP Developed in Embarcadero C++ Builder
A Check of the Open-Source Project WinSCP Developed in Embarcadero C++ BuilderA Check of the Open-Source Project WinSCP Developed in Embarcadero C++ Builder
A Check of the Open-Source Project WinSCP Developed in Embarcadero C++ BuilderAndrey Karpov
 
PyParis 2017 / Writing a C Python extension in 2017, Jean-Baptiste Aviat
PyParis 2017 / Writing a C Python extension in 2017, Jean-Baptiste Aviat PyParis 2017 / Writing a C Python extension in 2017, Jean-Baptiste Aviat
PyParis 2017 / Writing a C Python extension in 2017, Jean-Baptiste Aviat Pôle Systematic Paris-Region
 
嵌入式Linux課程-GNU Toolchain
嵌入式Linux課程-GNU Toolchain嵌入式Linux課程-GNU Toolchain
嵌入式Linux課程-GNU Toolchain艾鍗科技
 
Advanced Python Tutorial | Learn Advanced Python Concepts | Python Programmin...
Advanced Python Tutorial | Learn Advanced Python Concepts | Python Programmin...Advanced Python Tutorial | Learn Advanced Python Concepts | Python Programmin...
Advanced Python Tutorial | Learn Advanced Python Concepts | Python Programmin...Edureka!
 

Similar to Sphinx autodoc - automated api documentation - PyCon.MY 2015 (20)

Intro to Python
Intro to PythonIntro to Python
Intro to Python
 
Intro
IntroIntro
Intro
 
Flask jwt authentication tutorial
Flask jwt authentication tutorialFlask jwt authentication tutorial
Flask jwt authentication tutorial
 
Presentation of Python, Django, DockerStack
Presentation of Python, Django, DockerStackPresentation of Python, Django, DockerStack
Presentation of Python, Django, DockerStack
 
descriptive programming
descriptive programmingdescriptive programming
descriptive programming
 
Ts archiving
Ts   archivingTs   archiving
Ts archiving
 
Write better python code with these 10 tricks | by yong cui, ph.d. | aug, 202...
Write better python code with these 10 tricks | by yong cui, ph.d. | aug, 202...Write better python code with these 10 tricks | by yong cui, ph.d. | aug, 202...
Write better python code with these 10 tricks | by yong cui, ph.d. | aug, 202...
 
node.js, javascript and the future
node.js, javascript and the futurenode.js, javascript and the future
node.js, javascript and the future
 
обзор Python
обзор Pythonобзор Python
обзор Python
 
These questions will be a bit advanced level 2
These questions will be a bit advanced level 2These questions will be a bit advanced level 2
These questions will be a bit advanced level 2
 
Scripting as a Second Language
Scripting as a Second LanguageScripting as a Second Language
Scripting as a Second Language
 
Symfony finally swiped right on envvars
Symfony finally swiped right on envvarsSymfony finally swiped right on envvars
Symfony finally swiped right on envvars
 
Static code analysis: what? how? why?
Static code analysis: what? how? why?Static code analysis: what? how? why?
Static code analysis: what? how? why?
 
CoffeeScript Design Patterns
CoffeeScript Design PatternsCoffeeScript Design Patterns
CoffeeScript Design Patterns
 
A Check of the Open-Source Project WinSCP Developed in Embarcadero C++ Builder
A Check of the Open-Source Project WinSCP Developed in Embarcadero C++ BuilderA Check of the Open-Source Project WinSCP Developed in Embarcadero C++ Builder
A Check of the Open-Source Project WinSCP Developed in Embarcadero C++ Builder
 
Dynamic Python
Dynamic PythonDynamic Python
Dynamic Python
 
Python1
Python1Python1
Python1
 
PyParis 2017 / Writing a C Python extension in 2017, Jean-Baptiste Aviat
PyParis 2017 / Writing a C Python extension in 2017, Jean-Baptiste Aviat PyParis 2017 / Writing a C Python extension in 2017, Jean-Baptiste Aviat
PyParis 2017 / Writing a C Python extension in 2017, Jean-Baptiste Aviat
 
嵌入式Linux課程-GNU Toolchain
嵌入式Linux課程-GNU Toolchain嵌入式Linux課程-GNU Toolchain
嵌入式Linux課程-GNU Toolchain
 
Advanced Python Tutorial | Learn Advanced Python Concepts | Python Programmin...
Advanced Python Tutorial | Learn Advanced Python Concepts | Python Programmin...Advanced Python Tutorial | Learn Advanced Python Concepts | Python Programmin...
Advanced Python Tutorial | Learn Advanced Python Concepts | Python Programmin...
 

More from Takayuki Shimizukawa

Navigating Python: Milestones from Essential Reads
Navigating Python: Milestones from Essential ReadsNavigating Python: Milestones from Essential Reads
Navigating Python: Milestones from Essential ReadsTakayuki Shimizukawa
 
Django ORM道場:クエリの基本を押さえ,より良い形を身に付けよう
Django ORM道場:クエリの基本を押さえ,より良い形を身に付けようDjango ORM道場:クエリの基本を押さえ,より良い形を身に付けよう
Django ORM道場:クエリの基本を押さえ,より良い形を身に付けようTakayuki Shimizukawa
 
OpenTelemetryでWebシステムの処理を追跡しよう - DjangoCongress JP 2022
OpenTelemetryでWebシステムの処理を追跡しよう - DjangoCongress JP 2022OpenTelemetryでWebシステムの処理を追跡しよう - DjangoCongress JP 2022
OpenTelemetryでWebシステムの処理を追跡しよう - DjangoCongress JP 2022Takayuki Shimizukawa
 
プログラマーとの出会い - Hello, Programmer! at PyCon Kyushu 2022
プログラマーとの出会い - Hello, Programmer! at PyCon Kyushu 2022プログラマーとの出会い - Hello, Programmer! at PyCon Kyushu 2022
プログラマーとの出会い - Hello, Programmer! at PyCon Kyushu 2022Takayuki Shimizukawa
 
Webアプリを並行開発する際のマイグレーション戦略
Webアプリを並行開発する際のマイグレーション戦略Webアプリを並行開発する際のマイグレーション戦略
Webアプリを並行開発する際のマイグレーション戦略Takayuki Shimizukawa
 
『自走プログラマー』 が我々に必要だった理由
『自走プログラマー』 が我々に必要だった理由『自走プログラマー』 が我々に必要だった理由
『自走プログラマー』 が我々に必要だった理由Takayuki Shimizukawa
 
エキスパートPythonプログラミング改訂3版の読みどころ
エキスパートPythonプログラミング改訂3版の読みどころエキスパートPythonプログラミング改訂3版の読みどころ
エキスパートPythonプログラミング改訂3版の読みどころTakayuki Shimizukawa
 
RLSを用いたマルチテナント実装 for Django
RLSを用いたマルチテナント実装 for DjangoRLSを用いたマルチテナント実装 for Django
RLSを用いたマルチテナント実装 for DjangoTakayuki Shimizukawa
 
独学プログラマーのその後
独学プログラマーのその後独学プログラマーのその後
独学プログラマーのその後Takayuki Shimizukawa
 
【修正版】Django + SQLAlchemy: シンプルWay
【修正版】Django + SQLAlchemy: シンプルWay【修正版】Django + SQLAlchemy: シンプルWay
【修正版】Django + SQLAlchemy: シンプルWayTakayuki Shimizukawa
 
Sphinx customization for OGP support at SphinxCon JP 2018
Sphinx customization for OGP support at SphinxCon JP 2018Sphinx customization for OGP support at SphinxCon JP 2018
Sphinx customization for OGP support at SphinxCon JP 2018Takayuki Shimizukawa
 
Pythonはどうやってlen関数で長さを手にいれているの?
Pythonはどうやってlen関数で長さを手にいれているの?Pythonはどうやってlen関数で長さを手にいれているの?
Pythonはどうやってlen関数で長さを手にいれているの?Takayuki Shimizukawa
 
仕事で使うちょっとしたコードをOSSとして開発メンテしていく - Django Redshift Backend の開発 - PyCon JP 2016
仕事で使うちょっとしたコードをOSSとして開発メンテしていく- Django Redshift Backend の開発 - PyCon JP 2016仕事で使うちょっとしたコードをOSSとして開発メンテしていく- Django Redshift Backend の開発 - PyCon JP 2016
仕事で使うちょっとしたコードをOSSとして開発メンテしていく - Django Redshift Backend の開発 - PyCon JP 2016Takayuki Shimizukawa
 
素振りのススメ at Python入門者の集い
素振りのススメ at Python入門者の集い素振りのススメ at Python入門者の集い
素振りのススメ at Python入門者の集いTakayuki Shimizukawa
 
世界のSphinx事情 @ SphinxCon JP 2015
世界のSphinx事情 @ SphinxCon JP 2015世界のSphinx事情 @ SphinxCon JP 2015
世界のSphinx事情 @ SphinxCon JP 2015Takayuki Shimizukawa
 
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介Takayuki Shimizukawa
 
Sphinxで作る貢献しやすい ドキュメント翻訳の仕組み
Sphinxで作る貢献しやすいドキュメント翻訳の仕組みSphinxで作る貢献しやすいドキュメント翻訳の仕組み
Sphinxで作る貢献しやすい ドキュメント翻訳の仕組みTakayuki Shimizukawa
 
Easy contributable internationalization process with Sphinx @ pyconsg2015
Easy contributable internationalization process with Sphinx @ pyconsg2015Easy contributable internationalization process with Sphinx @ pyconsg2015
Easy contributable internationalization process with Sphinx @ pyconsg2015Takayuki Shimizukawa
 
Easy contributable internationalization process with Sphinx (PyCon APAC 2015 ...
Easy contributable internationalization process with Sphinx (PyCon APAC 2015 ...Easy contributable internationalization process with Sphinx (PyCon APAC 2015 ...
Easy contributable internationalization process with Sphinx (PyCon APAC 2015 ...Takayuki Shimizukawa
 

More from Takayuki Shimizukawa (20)

Navigating Python: Milestones from Essential Reads
Navigating Python: Milestones from Essential ReadsNavigating Python: Milestones from Essential Reads
Navigating Python: Milestones from Essential Reads
 
IKEv2-VPN PyHackCon2023
IKEv2-VPN PyHackCon2023IKEv2-VPN PyHackCon2023
IKEv2-VPN PyHackCon2023
 
Django ORM道場:クエリの基本を押さえ,より良い形を身に付けよう
Django ORM道場:クエリの基本を押さえ,より良い形を身に付けようDjango ORM道場:クエリの基本を押さえ,より良い形を身に付けよう
Django ORM道場:クエリの基本を押さえ,より良い形を身に付けよう
 
OpenTelemetryでWebシステムの処理を追跡しよう - DjangoCongress JP 2022
OpenTelemetryでWebシステムの処理を追跡しよう - DjangoCongress JP 2022OpenTelemetryでWebシステムの処理を追跡しよう - DjangoCongress JP 2022
OpenTelemetryでWebシステムの処理を追跡しよう - DjangoCongress JP 2022
 
プログラマーとの出会い - Hello, Programmer! at PyCon Kyushu 2022
プログラマーとの出会い - Hello, Programmer! at PyCon Kyushu 2022プログラマーとの出会い - Hello, Programmer! at PyCon Kyushu 2022
プログラマーとの出会い - Hello, Programmer! at PyCon Kyushu 2022
 
Webアプリを並行開発する際のマイグレーション戦略
Webアプリを並行開発する際のマイグレーション戦略Webアプリを並行開発する際のマイグレーション戦略
Webアプリを並行開発する際のマイグレーション戦略
 
『自走プログラマー』 が我々に必要だった理由
『自走プログラマー』 が我々に必要だった理由『自走プログラマー』 が我々に必要だった理由
『自走プログラマー』 が我々に必要だった理由
 
エキスパートPythonプログラミング改訂3版の読みどころ
エキスパートPythonプログラミング改訂3版の読みどころエキスパートPythonプログラミング改訂3版の読みどころ
エキスパートPythonプログラミング改訂3版の読みどころ
 
RLSを用いたマルチテナント実装 for Django
RLSを用いたマルチテナント実装 for DjangoRLSを用いたマルチテナント実装 for Django
RLSを用いたマルチテナント実装 for Django
 
独学プログラマーのその後
独学プログラマーのその後独学プログラマーのその後
独学プログラマーのその後
 
【修正版】Django + SQLAlchemy: シンプルWay
【修正版】Django + SQLAlchemy: シンプルWay【修正版】Django + SQLAlchemy: シンプルWay
【修正版】Django + SQLAlchemy: シンプルWay
 
Sphinx customization for OGP support at SphinxCon JP 2018
Sphinx customization for OGP support at SphinxCon JP 2018Sphinx customization for OGP support at SphinxCon JP 2018
Sphinx customization for OGP support at SphinxCon JP 2018
 
Pythonはどうやってlen関数で長さを手にいれているの?
Pythonはどうやってlen関数で長さを手にいれているの?Pythonはどうやってlen関数で長さを手にいれているの?
Pythonはどうやってlen関数で長さを手にいれているの?
 
仕事で使うちょっとしたコードをOSSとして開発メンテしていく - Django Redshift Backend の開発 - PyCon JP 2016
仕事で使うちょっとしたコードをOSSとして開発メンテしていく- Django Redshift Backend の開発 - PyCon JP 2016仕事で使うちょっとしたコードをOSSとして開発メンテしていく- Django Redshift Backend の開発 - PyCon JP 2016
仕事で使うちょっとしたコードをOSSとして開発メンテしていく - Django Redshift Backend の開発 - PyCon JP 2016
 
素振りのススメ at Python入門者の集い
素振りのススメ at Python入門者の集い素振りのススメ at Python入門者の集い
素振りのススメ at Python入門者の集い
 
世界のSphinx事情 @ SphinxCon JP 2015
世界のSphinx事情 @ SphinxCon JP 2015世界のSphinx事情 @ SphinxCon JP 2015
世界のSphinx事情 @ SphinxCon JP 2015
 
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介JUS関西 Sphinxワークショップ@関西 Sphinx紹介
JUS関西 Sphinxワークショップ@関西 Sphinx紹介
 
Sphinxで作る貢献しやすい ドキュメント翻訳の仕組み
Sphinxで作る貢献しやすいドキュメント翻訳の仕組みSphinxで作る貢献しやすいドキュメント翻訳の仕組み
Sphinxで作る貢献しやすい ドキュメント翻訳の仕組み
 
Easy contributable internationalization process with Sphinx @ pyconsg2015
Easy contributable internationalization process with Sphinx @ pyconsg2015Easy contributable internationalization process with Sphinx @ pyconsg2015
Easy contributable internationalization process with Sphinx @ pyconsg2015
 
Easy contributable internationalization process with Sphinx (PyCon APAC 2015 ...
Easy contributable internationalization process with Sphinx (PyCon APAC 2015 ...Easy contributable internationalization process with Sphinx (PyCon APAC 2015 ...
Easy contributable internationalization process with Sphinx (PyCon APAC 2015 ...
 

Recently uploaded

Automation Ops Series: Session 3 - Solutions management
Automation Ops Series: Session 3 - Solutions managementAutomation Ops Series: Session 3 - Solutions management
Automation Ops Series: Session 3 - Solutions managementDianaGray10
 
Genislab builds better products and faster go-to-market with Lean project man...
Genislab builds better products and faster go-to-market with Lean project man...Genislab builds better products and faster go-to-market with Lean project man...
Genislab builds better products and faster go-to-market with Lean project man...Farhan Tariq
 
Testing tools and AI - ideas what to try with some tool examples
Testing tools and AI - ideas what to try with some tool examplesTesting tools and AI - ideas what to try with some tool examples
Testing tools and AI - ideas what to try with some tool examplesKari Kakkonen
 
Long journey of Ruby standard library at RubyConf AU 2024
Long journey of Ruby standard library at RubyConf AU 2024Long journey of Ruby standard library at RubyConf AU 2024
Long journey of Ruby standard library at RubyConf AU 2024Hiroshi SHIBATA
 
QMMS Lesson 2 - Using MS Excel Formula.pdf
QMMS Lesson 2 - Using MS Excel Formula.pdfQMMS Lesson 2 - Using MS Excel Formula.pdf
QMMS Lesson 2 - Using MS Excel Formula.pdfROWELL MARQUINA
 
All These Sophisticated Attacks, Can We Really Detect Them - PDF
All These Sophisticated Attacks, Can We Really Detect Them - PDFAll These Sophisticated Attacks, Can We Really Detect Them - PDF
All These Sophisticated Attacks, Can We Really Detect Them - PDFMichael Gough
 
Email Marketing Automation for Bonterra Impact Management (fka Social Solutio...
Email Marketing Automation for Bonterra Impact Management (fka Social Solutio...Email Marketing Automation for Bonterra Impact Management (fka Social Solutio...
Email Marketing Automation for Bonterra Impact Management (fka Social Solutio...Jeffrey Haguewood
 
Tampa BSides - The No BS SOC (slides from April 6, 2024 talk)
Tampa BSides - The No BS SOC (slides from April 6, 2024 talk)Tampa BSides - The No BS SOC (slides from April 6, 2024 talk)
Tampa BSides - The No BS SOC (slides from April 6, 2024 talk)Mark Simos
 
MuleSoft Online Meetup Group - B2B Crash Course: Release SparkNotes
MuleSoft Online Meetup Group - B2B Crash Course: Release SparkNotesMuleSoft Online Meetup Group - B2B Crash Course: Release SparkNotes
MuleSoft Online Meetup Group - B2B Crash Course: Release SparkNotesManik S Magar
 
Arti Languages Pre Seed Pitchdeck 2024.pdf
Arti Languages Pre Seed Pitchdeck 2024.pdfArti Languages Pre Seed Pitchdeck 2024.pdf
Arti Languages Pre Seed Pitchdeck 2024.pdfwill854175
 
Unleashing Real-time Insights with ClickHouse_ Navigating the Landscape in 20...
Unleashing Real-time Insights with ClickHouse_ Navigating the Landscape in 20...Unleashing Real-time Insights with ClickHouse_ Navigating the Landscape in 20...
Unleashing Real-time Insights with ClickHouse_ Navigating the Landscape in 20...Alkin Tezuysal
 
Transcript: New from BookNet Canada for 2024: BNC SalesData and LibraryData -...
Transcript: New from BookNet Canada for 2024: BNC SalesData and LibraryData -...Transcript: New from BookNet Canada for 2024: BNC SalesData and LibraryData -...
Transcript: New from BookNet Canada for 2024: BNC SalesData and LibraryData -...BookNet Canada
 
Bitdefender-CSG-Report-creat7534-interactive
Bitdefender-CSG-Report-creat7534-interactiveBitdefender-CSG-Report-creat7534-interactive
Bitdefender-CSG-Report-creat7534-interactivestartupro
 
Software Security in the Real World w/Kelsey Hightower
Software Security in the Real World w/Kelsey HightowerSoftware Security in the Real World w/Kelsey Hightower
Software Security in the Real World w/Kelsey HightowerAnchore
 
Accelerating Enterprise Software Engineering with Platformless
Accelerating Enterprise Software Engineering with PlatformlessAccelerating Enterprise Software Engineering with Platformless
Accelerating Enterprise Software Engineering with PlatformlessWSO2
 
Connecting the Dots for Information Discovery.pdf
Connecting the Dots for Information Discovery.pdfConnecting the Dots for Information Discovery.pdf
Connecting the Dots for Information Discovery.pdfNeo4j
 
How to Effectively Monitor SD-WAN and SASE Environments with ThousandEyes
How to Effectively Monitor SD-WAN and SASE Environments with ThousandEyesHow to Effectively Monitor SD-WAN and SASE Environments with ThousandEyes
How to Effectively Monitor SD-WAN and SASE Environments with ThousandEyesThousandEyes
 
Dublin_mulesoft_meetup_API_specifications.pptx
Dublin_mulesoft_meetup_API_specifications.pptxDublin_mulesoft_meetup_API_specifications.pptx
Dublin_mulesoft_meetup_API_specifications.pptxKunal Gupta
 
Generative Artificial Intelligence: How generative AI works.pdf
Generative Artificial Intelligence: How generative AI works.pdfGenerative Artificial Intelligence: How generative AI works.pdf
Generative Artificial Intelligence: How generative AI works.pdfIngrid Airi González
 
Top 10 Hubspot Development Companies in 2024
Top 10 Hubspot Development Companies in 2024Top 10 Hubspot Development Companies in 2024
Top 10 Hubspot Development Companies in 2024TopCSSGallery
 

Recently uploaded (20)

Automation Ops Series: Session 3 - Solutions management
Automation Ops Series: Session 3 - Solutions managementAutomation Ops Series: Session 3 - Solutions management
Automation Ops Series: Session 3 - Solutions management
 
Genislab builds better products and faster go-to-market with Lean project man...
Genislab builds better products and faster go-to-market with Lean project man...Genislab builds better products and faster go-to-market with Lean project man...
Genislab builds better products and faster go-to-market with Lean project man...
 
Testing tools and AI - ideas what to try with some tool examples
Testing tools and AI - ideas what to try with some tool examplesTesting tools and AI - ideas what to try with some tool examples
Testing tools and AI - ideas what to try with some tool examples
 
Long journey of Ruby standard library at RubyConf AU 2024
Long journey of Ruby standard library at RubyConf AU 2024Long journey of Ruby standard library at RubyConf AU 2024
Long journey of Ruby standard library at RubyConf AU 2024
 
QMMS Lesson 2 - Using MS Excel Formula.pdf
QMMS Lesson 2 - Using MS Excel Formula.pdfQMMS Lesson 2 - Using MS Excel Formula.pdf
QMMS Lesson 2 - Using MS Excel Formula.pdf
 
All These Sophisticated Attacks, Can We Really Detect Them - PDF
All These Sophisticated Attacks, Can We Really Detect Them - PDFAll These Sophisticated Attacks, Can We Really Detect Them - PDF
All These Sophisticated Attacks, Can We Really Detect Them - PDF
 
Email Marketing Automation for Bonterra Impact Management (fka Social Solutio...
Email Marketing Automation for Bonterra Impact Management (fka Social Solutio...Email Marketing Automation for Bonterra Impact Management (fka Social Solutio...
Email Marketing Automation for Bonterra Impact Management (fka Social Solutio...
 
Tampa BSides - The No BS SOC (slides from April 6, 2024 talk)
Tampa BSides - The No BS SOC (slides from April 6, 2024 talk)Tampa BSides - The No BS SOC (slides from April 6, 2024 talk)
Tampa BSides - The No BS SOC (slides from April 6, 2024 talk)
 
MuleSoft Online Meetup Group - B2B Crash Course: Release SparkNotes
MuleSoft Online Meetup Group - B2B Crash Course: Release SparkNotesMuleSoft Online Meetup Group - B2B Crash Course: Release SparkNotes
MuleSoft Online Meetup Group - B2B Crash Course: Release SparkNotes
 
Arti Languages Pre Seed Pitchdeck 2024.pdf
Arti Languages Pre Seed Pitchdeck 2024.pdfArti Languages Pre Seed Pitchdeck 2024.pdf
Arti Languages Pre Seed Pitchdeck 2024.pdf
 
Unleashing Real-time Insights with ClickHouse_ Navigating the Landscape in 20...
Unleashing Real-time Insights with ClickHouse_ Navigating the Landscape in 20...Unleashing Real-time Insights with ClickHouse_ Navigating the Landscape in 20...
Unleashing Real-time Insights with ClickHouse_ Navigating the Landscape in 20...
 
Transcript: New from BookNet Canada for 2024: BNC SalesData and LibraryData -...
Transcript: New from BookNet Canada for 2024: BNC SalesData and LibraryData -...Transcript: New from BookNet Canada for 2024: BNC SalesData and LibraryData -...
Transcript: New from BookNet Canada for 2024: BNC SalesData and LibraryData -...
 
Bitdefender-CSG-Report-creat7534-interactive
Bitdefender-CSG-Report-creat7534-interactiveBitdefender-CSG-Report-creat7534-interactive
Bitdefender-CSG-Report-creat7534-interactive
 
Software Security in the Real World w/Kelsey Hightower
Software Security in the Real World w/Kelsey HightowerSoftware Security in the Real World w/Kelsey Hightower
Software Security in the Real World w/Kelsey Hightower
 
Accelerating Enterprise Software Engineering with Platformless
Accelerating Enterprise Software Engineering with PlatformlessAccelerating Enterprise Software Engineering with Platformless
Accelerating Enterprise Software Engineering with Platformless
 
Connecting the Dots for Information Discovery.pdf
Connecting the Dots for Information Discovery.pdfConnecting the Dots for Information Discovery.pdf
Connecting the Dots for Information Discovery.pdf
 
How to Effectively Monitor SD-WAN and SASE Environments with ThousandEyes
How to Effectively Monitor SD-WAN and SASE Environments with ThousandEyesHow to Effectively Monitor SD-WAN and SASE Environments with ThousandEyes
How to Effectively Monitor SD-WAN and SASE Environments with ThousandEyes
 
Dublin_mulesoft_meetup_API_specifications.pptx
Dublin_mulesoft_meetup_API_specifications.pptxDublin_mulesoft_meetup_API_specifications.pptx
Dublin_mulesoft_meetup_API_specifications.pptx
 
Generative Artificial Intelligence: How generative AI works.pdf
Generative Artificial Intelligence: How generative AI works.pdfGenerative Artificial Intelligence: How generative AI works.pdf
Generative Artificial Intelligence: How generative AI works.pdf
 
Top 10 Hubspot Development Companies in 2024
Top 10 Hubspot Development Companies in 2024Top 10 Hubspot Development Companies in 2024
Top 10 Hubspot Development Companies in 2024
 

Sphinx autodoc - automated api documentation - PyCon.MY 2015

  • 3. Who am I @shimizukawa 1. Sphinx co-maintainer 2. Sphinx-users.jp 3. PyCon JP committee  BePROUD co, ltd. 3
  • 5. 5
  • 6. Do you know the docstring? 6
  • 7. 1. def dumps(obj, ensure_ascii=True): 2. """Serialize ``obj`` to a JSON formatted ``str``. 3. """ 4. 5. ... 6. return ... Line 2,3 is a docstring You can see the string by "help(dumps)" Docstring 7
  • 8. Have you written API docs using docstrings? 8
  • 9. What is the reason you do not write docstrings.  I don't know what/where should I write.  Are there some docstring format spec?  It's not beneficial. I'll tell you a good way to write the docstrings. 9
  • 10. Goal of this session  How to generate a doc from Python source code.  re-discovering the meaning of docstrings. 10
  • 11. 11
  • 12. What is Sphinx? 12 Sphinx is a documentation generator Sphinx generates doc as several output formats from the reST text markup Sphinx reSTreSTreStructuredText (reST) reST Parser HTML Builder ePub Builder LaTeX Builder texlive HTML theme Favorite Editor
  • 13. The history of Sphinx (short ver.) 13 The father of Sphinx Too hard to maintenance ~2007 Easy to write Easy to maintenance 2007~
  • 14. Sphinx Before and After Before  There was no standard ways to write documents  Sometime, we need converting markups into other formats After  Generate multiple output format from single source  Integrated html themes make read docs easier  API references can be integrated into narrative docs  Automated doc building and hosting by ReadTheDocs 14
  • 15. Many docs are written by Sphinx For examples  Python libraries/tools: Python, Sphinx, Flask, Jinja2, Django, Pyramid, SQLAlchemy, Numpy, SciPy, scikit-learn, pandas, fabric, ansible, awscli, …  Non python libraries/tools: Chef, CakePHP(2.x), MathJax, Selenium, Varnish 15
  • 16. Many docs are written by Sphinx For examples  Python libraries/tools: Python, Sphinx, Flask, Jinja2, Django, Pyramid, SQLAlchemy, Numpy, SciPy, scikit-learn, pandas, fabric, ansible, awscli, …  Non python libraries/tools: Chef, CakePHP(2.x), MathJax, Selenium, Varnish 16
  • 17. Sphinx extensions (built-in) Sphinx provides these extensions to support automated API documentation.  sphinx.ext.autodoc  sphinx.ext.autosummary  sphinx.ext.doctest  sphinx.ext.coverage Sphinx reST Parser HTML Builder ePub Builder LaTeX Builder docutils autosummary autodoc doctest coverage 17
  • 18. library code example 1. "utility functions" 2. 3. def dumps(obj, ensure_ascii=True): 4. """Serialize ``obj`` to a JSON formatted ``str``. 5. """ 6. ... deep_thought/utils.py $ tree /path/to/your-code +- deep_thought | +- __init__.py | +- api.py | +- calc.py | +- utils.py +- setup.py 18
  • 19. $ pip install sphinx  Your code and sphinx should be in single python environment.  Python version is also important. How to install Sphinx 19
  • 20. $ cd /path/to/your-code $ sphinx-quickstart doc -m ... Project name: Deep thought Author name(s): Mice Project version: 0.7.5 ... ... Finished  "-m" to generate minimal Makefile/make.bat  -m is important to introduce this session easily. How to start a Sphinx project Keep pressing ENTER key 20 Create a doc directory
  • 21. $ cd doc $ make html ... Build finished. The HTML pages are in _build/html. "make html" command generates html files into _build/html. make html once 21
  • 22. Current files structure $ tree /path/to/your-code +- deep_thought | +- __init__.py | +- api.py | +- calc.py | +- utils.py +- doc | +- _build/ | | +- html/ | +- _static/ | +- _template/ | +- conf.py | +- index.rst | +- make.bat | +- Makefile +- setup.py Scaffold files Build output Library files 22
  • 23. 23
  • 24. $ tree /path/to/your-code +- deep_thought | +- __init__.py | +- api.py | +- calc.py | +- utils.py +- doc | +- _build/ | | +- html/ | +- _static/ | +- _template/ | +- conf.py | +- index.rst | +- make.bat | +- Makefile +- setup.py 1. import os 2. import sys 3. sys.path.insert(0, os.path.abspath('..')) 4. extensions = [ 5. 'sphinx.ext.autodoc', 6. ] setup autodoc extension doc/conf.py 24 Line-3: add your library path to import them from Sphinx autodoc. Line-5: add 'sphinx.ext.autodoc' to use the extension.
  • 25. Add automodule directive to your doc 1. Deep thought API 2. ================ 3. 4. .. automodule:: deep_thought.utils 5. :members: 6. 1. "utility functions" 2. 3. def dumps(obj, ensure_ascii=True): 4. """Serialize ``obj`` to a JSON formatted ``str``. 5. """ 6. ... doc/index.rst 25 deep_thought/utils.py Line-4: automodule directive import specified module and inspect the module. Line-5: :members: option will inspects all members of module not only module docstring.
  • 26. $ cd doc $ make html ... Build finished. The HTML pages are in _build/html. make html 26
  • 27. How does it work? autodoc directive generates intermediate reST internally: 1. Deep thought API 2. ================ 3. 4. .. py:module:: deep_thought.utils 5. 6. utility functions 7. 8. .. py:function:: dumps(obj, ensure_ascii=True) 9. :module: deep_thought.utils 10. 11. Serialize ``obj`` to a JSON formatted :class:`str`. doc/index.rst Intermediate reST 27
  • 28. $ make html SPHINXOPTS=-vvv ... ... [autodoc] output: .. py:module:: deep_thought.utils utility functions .. py:function:: dumps(obj, ensure_ascii=True) :module: deep_thought.utils Serialize ``obj`` to a JSON formatted :class:`str`. You can see the reST with -vvv option 28
  • 29. Take care! Sphinx autodoc import your code to get docstrings. It means autodoc will execute code at module global level. 29
  • 30. Danger code 1. import os 2. 3. def delete_world(): 4. os.system('sudo rm -Rf /') 5. 6. delete_world() # will be executed at "make html" danger.py 30
  • 31. execution guard on import 1. import os 2. 3. def delete_world(): 4. os.system('sudo rm -Rf /') 5. 6. delete_world() # will be executed at "make html" danger.py 1. import os 2. 3. def delete_world(): 4. os.system('sudo rm -Rf /') 5. 6. if __name__ == '__main__': 7. delete_world() # doesn't execute at "make html" safer.py Execution guard 31
  • 32. execution guard on import 1. import os 2. 3. def delete_world(): 4. os.system('sudo rm -Rf /') 5. 6. delete_world() # will be executed at "make html" danger.py 1. import os 2. 3. def delete_world(): 4. os.system('sudo rm -Rf /') 5. 6. if __name__ == '__main__': 7. delete_world() # doesn't execute at "make html" safer.py Execution guard 32
  • 33. "Oh, I can't understand the type of arguments and meanings even reading this!" 33 Lacking necessary information
  • 34. 1. def dumps(obj, ensure_ascii=True): 2. """Serialize ``obj`` to a JSON formatted 3. :class:`str`. 4. 5. :param dict obj: dict type object to serialize. 6. :param bool ensure_ascii: Default is True. If 7. False, all non-ASCII characters are not ... 8. :return: JSON formatted string 9. :rtype: str 10. """  http://sphinx-doc.org/domains.html#info-field-lists "info field lists" for arguments deep_thought/utils.py 34
  • 35. def dumps(obj, ensure_ascii=True): """Serialize ``obj`` to a JSON formatted :class:`str`. :param dict obj: dict type object to serialize. :param bool ensure_ascii: Default is True. If False, all non-ASCII characters are not ... :return: JSON formatted string :rtype: str """ ... "info field lists" for arguments deep_thought/utils.py 35
  • 36. Cross-reference to functions 1. Examples 2. ========== 3. 4. This is a usage of :func:`deep_thought.utils.dumps` blah blah blah. ... examples.py reference (hyper link) 36
  • 37. 37
  • 38. Code example in a docstring 1. def dumps(obj, ensure_ascii=True): 2. """Serialize ``obj`` to a JSON formatted 3. :class:`str`. 4. 5. For example: 6. 7. >>> from deep_thought.utils import dumps 8. >>> data = dict(spam=1, ham='egg') 9. >>> dumps(data) 10. '{spam: 1, ham: "egg"}' 11. 12. :param dict obj: dict type object to serialize. 13. :param bool ensure_ascii: Default is True. If 14. False, all non-ASCII characters are not ... deep_thought/utils.py 38 doctest block You can copy & paste the red lines from python interactive shell.
  • 39. Syntax highlighted output $ make html ... rendered doctest block 39
  • 40.  You can expect that developers will update code examples when the interface is changed. We expect ... 1. def dumps(obj, ensure_ascii=True): 2. """Serialize ``obj`` to a JSON formatted 3. :class:`str`. 4. 5. For example: 6. 7. >>> from deep_thought.utils import dumps 8. >>> data = dict(spam=1, ham='egg') 9. >>> dumps(data) 10. '{spam: 1, ham: "egg"}' The code example is very close from implementation!! deep_thought/utils.py 40
  • 43. 1. ... 2. 3. extensions = [ 4. 'sphinx.ext.autodoc', 5. 'sphinx.ext.doctest', 6. ] 7.  Line-5: add 'sphinx.ext.doctest' extension. setup doctest extension doc/conf.py append 43
  • 44. $ make doctest ... Document: api ------------- ******************************************************** File "api.rst", line 11, in default Failed example: dumps(data) Expected: '{spam: 1, ham: "egg"}' Got: 'to-be-implemented' ... make: *** [doctest] Error 1 Result of "make doctest" 44 Result of doctest
  • 45. 45
  • 46. Individual pages for each modules api.html calc.html utils.html 46 1. deep_thought.utils 2. =================== 3. .. automodule:: deep_thought.utils 4. :members: doc/deep_thought.utils.rst
  • 47. 1. deep_thought.utils 2. =================== 3. .. automodule:: deep_thought.utils 4. :members: Add automodule directive to your doc doc/deep_thought.utils.rst 1. deep_thought.calc 2. ================== 3. .. automodule:: deep_thought.calc 4. :members: 1. deep_thought.api 2. ================== 3. .. automodule:: deep_thought.api 4. :members: doc/deep_thought.calc.rst doc/deep_thought.api.rst And many many reST files ... 47
  • 50. 1. ... 2. 3. extensions = [ 4. 'sphinx.ext.autodoc', 5. 'sphinx.ext.doctest', 6. 'sphinx.ext.autosummary', 7. ] 8. autodoc_default_flags = ['members'] 9. autosummary_generate = True 10.  Line-9: autosummary_generate = True generates reST files what you will specify with using autosummary directive. setup autosummary extension doc/conf.py append append append 50
  • 51. 1. Deep thought API 2. ================ 3. 4. .. autosummary:: 5. :toctree: generated 6. 7. deep_thought.api 8. deep_thought.calc 9. deep_thought.utils 10. Replace automodule with autosummary doc/index.rst $ make html ... 51
  • 52. Output of autosummary autosummary directive become TOC for each module pages. 52
  • 53. 53
  • 54. 1. def spam(): 2. ... 3. return res 4. 5. def ham(): 6. ... 7. return res 8. 9. def egg(): 10. ... 11. return res How to find undocumented funcs? doc/nodoc.py 54
  • 56. 1. ... 2. 3. extensions = [ 4. 'sphinx.ext.autodoc', 5. 'sphinx.ext.doctest', 6. 'sphinx.ext.autosummary', 7. 'sphinx.ext.coverage', 8. ] 9. autodoc_default_flags = ['members'] 10. autosummary_generate = True setup coverage extension doc/conf.py append  Line-7: add 'sphinx.ext.coverage' extension. 56
  • 57. make coverage and check the result $ make coverage ... Testing of coverage in the sources finished, look at the results in _buildcoverage. $ ls _build/coverage c.txt python.txt undoc.pickle 1. Undocumented Python objects 2. =========================== 3. deep_thought.utils 4. ------------------ 5. Functions: 6. * egg _build/coverage/python.txt This function doesn't have a doc! 57
  • 58. CAUTION! 1. Undocumented Python objects 2. =========================== 3. deep_thought.utils 4. ------------------ 5. Functions: 6. * egg python.txt $ make coverage ... Testing of coverage in the sources finished, look at the results in _buildcoverage. $ ls _build/coverage c.txt python.txt undoc.pickle The command always return ZERO coverage.xml is not exist reST format for whom? 58
  • 59. Let's make Pull-Request! We are waiting for your contribution to solve the problem. (bow) 59
  • 60. 60
  • 61. Why don't you write docstrings?  I don't know what/where should I write.  Let's write a description, arguments and doctest blocks at the next line of function signature.  Are there some docstring format spec?  Yes, you can use "info field list" for argument spec and you can use doctest block for code example.  It's not beneficial.  You can use autodoc, autosummary, doctest and coverage to make it beneficial. 61
  • 62. 62
  • 64. Options for autodoc  :members: blah  To document just specified members. Empty is ALL.  :undoc-members: ...  To document members which doesn't have docstring.  :private-members: ...  To document private members which name starts with underscore.  :special-members: ...  To document starts with underscore underscore.  :inherited-members: ...  To document inherited from super class. 64
  • 65. 2. Directives for Web API sphinxcontrib-httpdomain 65
  • 66. sphinxcontrib-httpdomain extension http domain's get directive render page render routing table (index) http highlighter It also contains sphinxcontrib.autohttp.flask, .bottle, .tornado extensions Listing New Index 66
  • 67. 3. Directives for Diagram sphinxcontrib-blockdiag sphinxcontrib-sqdiag sphinxcontrib-actdiag sphinxcontrib-nwdiag 67
  • 68. blockdiag series 68 http://blockdiag.com/ blockdiag seqdiag (sequence) actdiag (activity) nwdiag (network) packetdiag (packet) is included in nwdiag
  • 69. class Request(object): """ .. seqdiag:: { code [label="Your Code"]; lib [label="Library"]; site [label="Web Site"]; code -> lib [label="Request(url)"]; code <-- lib [label="req"]; code -> lib [label="req.open(auth_cb)"]; lib -> site [label="GET"]; lib <-- site [label="status=401"]; lib => code [label="auth_cb(realm)", ... lib -> site [label="GET/auth header"]; lib <-- site [label="status=200"]; code <-- lib [label="status"]; } """ sphinxcontrib-seqdiag extension 69 deep_thought/api.py extensions = [ 'sphinxcontrib.seqdiag', ] conf.py $ pip install sphinxcontrib-seqdiag
  • 71. Translation into other languages $ make gettext ... Build finished. The message catalogs are in _build/gettext. $ sphinx-intl update -p _build/gettext -l es #: ../../../deep_thought/utils.pydocstring of deep_thought. msgid "Serialize ``obj`` to a JSON formatted :class:`str`." msgstr "Serializar ``obj`` a un formato JSON :class:`str`." msgid "For example:" msgstr "Por ejemplo:" locale/es/LC_MESSAGES/generated.po language = 'es' locale_dirs = ['locale'] conf.py $ make html ... Build finished. The HTML pages are in _build/html. 71

Editor's Notes

  1. (ここの文字サイズ大きくする、マウスをレーザーポインタにする) Hi everyone. Thank you for coming my session. This session title is: Sphinx autodoc – automated API documentation
  2. こんにちは
  3. At first, Let me introduce myself. My name is Takayuki Shimizukawa came from Japan. I do 3 opensource works. 1. Sphinx co-maintainer since the end of 2011. 2. organize Sphinx-users.jp users group in Japan. 3. member of PyCon JP Committee. And I'm working for BePROUD. We develop web applications for business customers with using Django, Pyramid, SQLAlchemy, Sphinx and other python related tools.
  4. Before my main presentation, I'd like to introduce "PyCon JP 2015" in Tokyo Japan. We will held the event in this October. Registration is opened. Please join us. Anyway.
  5. Sphinx autodoc. This is a main topic of this session. Autodoc is a feature that is automatic document generation from source code. Autodoc uses the function definitions and also uses docstring of the such functions. Before we jump in the main topic, I want to know how many people know the docstring, and how many people writing the docstring.
  6. Docstring is a feature of Python. Do you know the docstring? How many people know that? Please raise your hand. 10, 20, 30.. 55 hands. Thanks. Hum, It might be a minor feature of Python.
  7. OK, This red lines is a docstring. Docstring describe a way of using the function that is written at the first line of the function body. When you type "help(dumps)" in a Python interactive shell, you will get the docstring.
  8. Have you written API docs as docstrings? Please raise again. 10, 20.. 22.5 hands. Thanks. It's very small number of hands. But some people write a docstrings.
  9. So, what is the reason you do not write them? Someone would say, * I don't know what/where should I write them. * Are there some specific docstring formats? * It's not beneficial. For example, sometimes docstrings are not updated even the function's behavior is changed. Those opinions are understandable So then, I'll explain you how to write the docstrings.
  10. Goal of this session. First one is, * How to generate a doc from Python source code. Second one is, * re-discovering the meaning of docstrings. OK, let's move forward.
  11. Sphinx autodoc is the most useful way to activate docstrings. So, before talking about docstrings, I'll introduce a basic of sphinx and How to Setup it.
  12. What is Sphinx? Sphinx is a documentation generator. Sphinx generates doc as several output formats from reStructuredText markup that is an extensible. (ポインタでinputとoutputを指す)
  13. The history of Sphinx. This man, Georg Brandl is the father of Sphinx. (クリック) Until 2007, python official document was written by LaTeX. But, it's too hard to maintenance. Georg was trying to change such situation. (クリック) So then, he created the Sphinx in 2007. The sphinx provides ease of use and maintainability for the Python official document.
  14. Sphinx before and after. Before There was no standard ways to write documents. One of example is a Python official document. It was written by LaTeX and several some python scripts jungle. And, Sometime, we need converting markups into other formats Since sphinx has been released, * We can generate more multiple output format from single source. * Integrated html themes make read docs easier. * API references can be integrated into narrative docs. * Automated doc building and hosting by ReadTheDocs service.
  15. Nowadays, sphinx has been used by these libraries and tools. Python libraries/tools: Python, Sphinx, Flask, Jinja2, Django, Pyramid, SQLAlchemy, Numpy, SciPy, scikit-learn, pandas, fabric, ansible, awscli, … And Non python library/tools also using Sphinx for them docs: Chef, CakePHP(2.x), MathJax, Selenium, Varnish
  16. Nowadays, sphinx has been used by these libraries and tools. Python libraries/tools: Python, Sphinx, Flask, Jinja2, Django, Pyramid, SQLAlchemy, Numpy, SciPy, scikit-learn, pandas, fabric, ansible, awscli, … And Non python library/tools also using Sphinx for them docs: Chef, CakePHP(2.x), MathJax, Selenium, Varnish
  17. Sphinx provides these extensions to support automated API documentation. sphinx.ext.autodoc sphinx.ext.autosummary sphinx.ext.doctest sphinx.ext.coverage Autodoc is the most important feature of sphinx. Almost python related libraries are using the autodoc feature.
  18. OK, let's setup a sphinx project for this code, for example. This library will be used in place of your code to explain autodoc feature. The library name is "Deep Thought". This is a structure of the library. The library has three modules: api.py, calc.py and utils.py. Second box is a first lines of program code in utils.py.
  19. If you don’t have sphinx installation in your environment, you need to install the Sphinx by this command. pip install sphinx Please note that your source code and sphinx should be installed in single python environment. Python version is also important. If you install Sphinx into Python3 environment in spite of your code is written in Python2, autodoc will emit exception to import your Python2 source code.
  20. Once you installed the sphinx, you can generate your documentation scaffold by using "sphinx-quickstart" command. Then interactive wizard is invoked and it requires Project name, Author name and Project version. The wizard also ask you many questions, but, DON'T PANIC, Usually, all you need is keep pressing Enter key. Note that, -m option is important. If you invoke without the option, you will get a "hard-coded make targets" Makefile, that will annoy you. And my presentation slide stand on this option. This option is introduced since Sphinx-1.3. And -m option will become default from Spihnx-1.5.
  21. So, type "make html" in doc directory to generate html output. You can see the output in _build/html directory.
  22. Now you can see the directories/files structure, like this. Library files under deep_thought directory. Build output under doc directory. Scaffold files under doc directory. In particular, you will see well utils.py, conf.py and index.rst in this session.
  23. Now we ready to go. Generate API docs from your python source code.
  24. Setup sphinx autodoc extension. This is a conf.py file in your sphinx scaffold. What is important is the third and fifth lines. Line-3rd: add your library path to import them from Sphinx autodoc. Line-5th: add 'sphinx.ext.autodoc' to use the extension. Next, let's specify the modules you want to document.
  25. Add automodule directive to your doc. First box is a utils.py file that is a part of deep_thought example library. Second box is a reST file. You can see the automodule usage in this box. automodule is a sphinx directive syntax that is provided by autodoc extension to generate document. Let's see the second box. (クリック) Line-4th: automodule directive imports specified module and inspect it. In this case, deepthought.utils module will be imported and be inspected. Line-5th: :members: option will inspects all members of module not only just module docstring. OK, we are now all ready. Let's invoke "make html" again.
  26. So, as a result of "make html", you can get a automatically generated document from .py file. Internally, automodule directive inspects your module and render the function signature, arguments and docstring.
  27. How does it work? autodoc directive generates intermediate reST, like this. Actually intermediate file is not generated in your filesystem, just created it on memory.
  28. If you want to see the intermediate reST lines, you can use -vvv option, like this. As you see, automodule directive is replaced with concrete documentation contents.
  29. But, please take care. Sphinx autodoc import your code to get docstrings. It means autodoc will execute code at module global level. Let me introduce a bad case related to this.
  30. This module will remove all your files. danger.py was designed as command-line script instead of "import from other module". If you tried to document with using autodoc, delete_world function will be called. Consequence of this, "make html" will destroy all your files.
  31. On the other hand, safer.py (lower block) using execution guard. It's very famous python's idiom.
  32. Because of the execution guard, your files will not be removed by make html. As a practical matter, you shouldn't try to document your setup.py for your package with using autodoc.
  33. Now let's return to the docstring and its output. This output lacks necessary information. It is the information of the argument. If you are looking for the API reference, and you find it, you will say; "Oh, I can't understand the type of arguments and meanings even reading this!"
  34. In this case, you can use "info field list" syntax for describing arguments. A real docstring should have descriptions for each function arguments like this. These red parts are special version of "field list" that called "info field lists". The specification of info field lists is described at the URL page.
  35. Info field lists is rendered as this. The output is quite nice. So, you will say; "Oh, I can understand it!", maybe.
  36. Cross-reference to functions. You can easily make cross-reference from other location to the dumps function. Of course, the cross-references beyond the pages.
  37. So far, I introduced the basics of autodoc. Following subject is: Detect deviations of the implementation and document. By using doctest.
  38. I think good API has a good document that illustrate usages of the API by using code example. If doc has code example, you can grasp the API usage quickly and exactly. I add a code example, such 4 red lines to docstring earlier. (クリック) It's called "doctest block". Obviously, this look is an interactive content of the python interactive shell. Actually, you can copy & paste the red lines from python interactive shell.
  39. After make html, You can get a syntax highlighted doctest block, like this. Library users can grasp the API usage quickly and exactly. And also users can try out it easily.
  40. And the point of view from library developers, code example is very close from implementation! We can expect that library developers will update code examples when the interface is changed by themselves. ... Really?
  41. Sorry, I don't believe it. If the code examples was very close from implementation, developers wouldn't mind to it. Because developers have no spare time to read the implicit rules from the code. Explicit is better than implicit for us.
  42. OK, let's use the doctest builder to detect deviations of the implementation and documentation.
  43. To use doctest builder, you need to add sphinx doctest extension to conf.py, like this. Line-5: add 'sphinx.ext.doctest' With only this, you are ready to use the doctest builder. OK, Let's invoke "make doctest" command.
  44. (OK, Let's invoke "make doctest" command.) After that, you can see the dumps function will provide us different result from the expected one. Expected one is: '{spam: 1, ham: "egg"}' Actual one is: 'to-be-implemented' it is not implemented properly yet. Anyway, by using the doctest builder, it show us differences in implementation and sample code in the documentation. Actually, if your UnitTest also contains doctests, you don't need to do this by Sphinx. However, if you don't write the UnitTest, "make doctest" would be a good place to start.
  45. Listing APIs automatically with using autosummary. As already noted, autodoc is very useful. However, if you have a lot of function of a lot of modules, ...
  46. And You want to have individual pages for each modules, you need to prepare many reST files for each modules. (クリック) This box is for utils.py. In this case you should also prepare such .rst files for api module and calc module. If you have 100 modules, you should prepare 100 .rst files.
  47. As you see, each reST files have just 4 lines. You can get them by repeating copy & paste & modify bit. However ... I believe that you don't want to repeat that, like this.
  48. Don't Repeat Yourself.
  49. OK, let's use the autosummary extension to avoid such a boring tasks.
  50. Setup sphinx autosummary extension. This is your conf.py again. Line-6th: to add 'sphinx.ext.autosummary' to use the extension. Line-8th: to use 'members' option for each autodoc related directives. Line-9th: to generate reST files what you will specify with using autosummary directive. //メモ: 9th to invoke 'sphinx-apidoc' internally. Default is False, in that case, you need to invoke 'sphinx-apidoc' by hand.
  51. You can use autosummary directive in your reST files as you see. This sample uses autosummary directive and toctree option. The :toctree: option is a directory location of intermediate files that will be generated by autosummary. And contents of autosummary directive, deep_thought.api, calc and utils, are module names you want to document. Thereby the autosummary, you will get 100 intermediate .rst files if you have 100 modules.
  52. After run "make html" command again. Finally, you can get each documented pages without forcing troublesome simple operations. Additionally, "autosummary" directive you wrote was generating table of contents that linking each module pages.
  53. Discovering undocumented APIs by using coverage extension.
  54. So far, we've automated the autodoc by using autosummary. In addition, now you can also find deviation of documents and implementation by using the doctest. But, how do you find a function that is not writing a docstring, at all?
  55. For such situation, we can use coverage extension to find undocumented functions, classes, methods.
  56. To use coverage extension, you should setup coverage extension to conf.py. This is your conf.py again. Line-7th: to add 'sphinx.ext.coverage' to use the extension. That's all!
  57. Let's invoke "make coverage" command. After that, you can get a result of coverage measurement. The coverage report is recorded in "_build/coverage/python.txt" that contains undocumented functions, classes and modules. As you see, you can get the undocumented function name.
  58. However, please take care that; Command always return 0 Then you can't distinguish the presence or absence of the undocumented function by the return code. IMO, it's fair enough because coverage command shouldn't fail regardless whether coverage is perfect or not. However, unfortunately, "make coverage" also unsupported to generate coverage.xml for Jenkins or some CI tools. As conclusion of this, you can discover the undocumented functions, but you can't integrate the information to a CI tools.
  59. Sorry for inconvenience. And we are waiting for your contribution to solve the problem.(bow)
  60. Let's review the reasons for not writing a docstring that was introduced at the beginning. I don't know what/where should I write. Let's write a description, arguments and doctest blocks at the next line of function signature. Are there some docstring format spec? Yes, you can use "info field list" for argument spec and you can use doctest block for code example. It's not beneficial. You can use autodoc, autosummary, doctest and coverage to make it beneficial. I think these reasons are resolved by using sphinx autodoc features, aren't you? Let's write docstrings, and use autodoc!
  61. At the end, I'd like to introduce some of the tips.
  62. First one is, Options.
  63. Options for autodo. :members: blah To document just specified members. If you specify the option without parameter, it means ALL. :undoc-members: ... To document members which doesn't have docstring. If you specify the option without parameter, all undocumented members are rendered. :private-members: ... To document private members which name starts with underscore. :special-members: ... To document starts with underscore underscore. :inherited-members: ... To document inherited from super class. Please refer to sphinx reference for the detail of options.
  64. Second one is Directives for Web API. It's sphinxcontrib-httpdomain.
  65. sphinxcontrib-httpdomain 3rd-party extension provides http domain to generate WebAPI doc. As you see, you can use get directive. Httpdomain also provides: Other http related directives "http" syntax highlighter It generates nice WebAPI reference page and well organized WebAPI index page. Httpdmain also contains sphinxcontrib.autohttp extension that support Flask, Bottle and Tornado WAF to document WebAPI methods automatically by using reflection.
  66. The 3rd one is directives for diagram. It's blockdiag series.
  67. blockdiag provides block style diagram from text notation. The series of blockdiag; seqdiag, actdiag, nwdiag, packetdiag, rackdiag are also released. These are standalone tool, so it works well without sphinx. And, blockdiag series for sphinx are also released. I'd like to introduce a sphinxcontrib-seqdiag example.
  68. This is a "sphinxcontrib-seqdiag" example. "seqdiag" provides sequence style diagram from text notation. At first, you need installation to use seqdiag directive in your document. Next, setup extension to your conf.py. And now, you can use seqdiag directive as you see. In this example, Request class docstring has seqdiag directive and notation. Finally, you'll get sequence diagram that is integrated to your documentation. So, you can describe a usage of API, behavior of API, and so on.
  69. The last one is Document translation.
  70. You can get translated output w/o editing reST and python code. For that, you can use "make gettext" command that generates gettext style pot files. "make gettext" extract text from reST file and python source file that referenced by autodoc. It means, you can translate them into any language without rewriting the original reST files and python source files. If you are interested, please join my tomorrow session!