Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
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 ...
...
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 forma...
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 m...
The history of Sphinx (short ver.)
13
The father of
Sphinx
Too hard to
maintenance
~2007
Easy to write
Easy to maintenance...
Sphinx Before and After
Before
 There was no standard ways to write documents
 Sometime, we need converting markups into...
Many docs are written by Sphinx
For examples
 Python libraries/tools:
Python, Sphinx, Flask, Jinja2, Django, Pyramid,
SQL...
Many docs are written by Sphinx
For examples
 Python libraries/tools:
Python, Sphinx, Flask, Jinja2, Django, Pyramid,
SQL...
Sphinx extensions (built-in)
Sphinx provides these extensions to support
automated API documentation.
 sphinx.ext.autodoc...
library code example
1. "utility functions"
2.
3. def dumps(obj, ensure_ascii=True):
4. """Serialize ``obj`` to a JSON for...
$ pip install sphinx
 Your code and sphinx should be in single
python environment.
 Python version is also important.
Ho...
$ cd /path/to/your-code
$ sphinx-quickstart doc -m
...
Project name: Deep thought
Author name(s): Mice
Project version: 0....
$ cd doc
$ make html
...
Build finished. The HTML pages are in _build/html.
"make html" command
generates html files into
...
Current files structure
$ tree /path/to/your-code
+- deep_thought
| +- __init__.py
| +- api.py
| +- calc.py
| +- utils.py
...
23
$ tree /path/to/your-code
+- deep_thought
| +- __init__.py
| +- api.py
| +- calc.py
| +- utils.py
+- doc
| +- _build/
| | ...
Add automodule directive to your doc
1. Deep thought API
2. ================
3.
4. .. automodule:: deep_thought.utils
5. :...
$ 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. ...
$ make html SPHINXOPTS=-vvv
...
...
[autodoc] output:
.. py:module:: deep_thought.utils
utility functions
.. py:function::...
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 a...
execution guard on import
1. import os
2.
3. def delete_world():
4. os.system('sudo rm -Rf /')
5.
6. delete_world() # will...
execution guard on import
1. import os
2.
3. def delete_world():
4. os.system('sudo rm -Rf /')
5.
6. delete_world() # will...
"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: ...
def dumps(obj, ensure_ascii=True):
"""Serialize ``obj`` to a JSON formatted :class:`str`.
:param dict obj: dict type objec...
Cross-reference to functions
1. Examples
2. ==========
3.
4. This is a usage of :func:`deep_thought.utils.dumps`
blah blah...
37
Code example in a docstring
1. def dumps(obj, ensure_ascii=True):
2. """Serialize ``obj`` to a JSON formatted
3. :class:`s...
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, ...
 ̄\_(ツ)_/ ̄
41
doctest builder
42
1. ...
2.
3. extensions = [
4. 'sphinx.ext.autodoc',
5. 'sphinx.ext.doctest',
6. ]
7.
 Line-5: add 'sphinx.ext.doctest' e...
$ make doctest
...
Document: api
-------------
********************************************************
File "api.rst", li...
45
Individual pages for each modules
api.html
calc.html
utils.html
46
1. deep_thought.utils
2. ===================
3. .. auto...
1. deep_thought.utils
2. ===================
3. .. automodule:: deep_thought.utils
4. :members:
Add automodule directive t...
 ̄\_(ツ)_/ ̄
48
autosummary extension
49
1. ...
2.
3. extensions = [
4. 'sphinx.ext.autodoc',
5. 'sphinx.ext.doctest',
6. 'sphinx.ext.autosummary',
7. ]
8. autodoc...
1. Deep thought API
2. ================
3.
4. .. autosummary::
5. :toctree: generated
6.
7. deep_thought.api
8. deep_thoug...
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 f...
coverage extension
55
1. ...
2.
3. extensions = [
4. 'sphinx.ext.autodoc',
5. 'sphinx.ext.doctest',
6. 'sphinx.ext.autosummary',
7. 'sphinx.ext....
make coverage and check the result
$ make coverage
...
Testing of coverage in the sources finished, look at the
results in...
CAUTION!
1. Undocumented Python objects
2. ===========================
3. deep_thought.utils
4. ------------------
5. Func...
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 docte...
62
1. Options
63
Options for autodoc
 :members: blah
 To document just specified members. Empty is ALL.
 :undoc-members: ...
 To docume...
2. Directives for Web API
sphinxcontrib-httpdomain
65
sphinxcontrib-httpdomain extension
http domain's get directive
render
page
render routing table (index)
http highlighter
I...
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 (pac...
class Request(object):
"""
.. seqdiag::
{
code [label="Your Code"];
lib [label="Library"];
site [label="Web Site"];
code -...
4. Document translation
70
Translation into other languages
$ make gettext
...
Build finished. The message catalogs are in
_build/gettext.
$ sphinx-i...
Questions?
@shimizukawa
Grab me after the session :)
72
Thanks :)
73
Upcoming SlideShare
Loading in …5
×

of

Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 1 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 2 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 3 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 4 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 5 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 6 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 7 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 8 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 9 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 10 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 11 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 12 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 13 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 14 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 15 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 16 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 17 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 18 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 19 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 20 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 21 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 22 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 23 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 24 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 25 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 26 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 27 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 28 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 29 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 30 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 31 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 32 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 33 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 34 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 35 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 36 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 37 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 38 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 39 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 40 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 41 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 42 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 43 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 44 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 45 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 46 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 47 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 48 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 49 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 50 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 51 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 52 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 53 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 54 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 55 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 56 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 57 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 58 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 59 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 60 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 61 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 62 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 63 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 64 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 65 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 66 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 67 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 68 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 69 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 70 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 71 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 72 Sphinx autodoc - automated api documentation - PyCon.MY 2015 Slide 73
Upcoming SlideShare
素振りのススメ at Python入門者の集い
Next
Download to read offline and view in fullscreen.

5 Likes

Share

Download to read offline

Sphinx autodoc - automated api documentation - PyCon.MY 2015

Download to read offline

Using the automated documentation feature of Sphinx, you can make with ease the extensive documentation of Python program.
You just write python function documents (docstrings), Sphinx organizes them into the document, can be converted to a variety of formats.
In this session, I'll explain a documentation procedure that uses with sphinx autodoc and autosummary extensions.

Related Books

Free with a 30 day trial from Scribd

See all

Sphinx autodoc - automated api documentation - PyCon.MY 2015

  1. 1. Takayuki Shimizukawa Sphinx co-maintainer Sphinx-users.jp 1
  2. 2. こんにちは Kon-Nichi-Wa 2
  3. 3. Who am I @shimizukawa 1. Sphinx co-maintainer 2. Sphinx-users.jp 3. PyCon JP committee  BePROUD co, ltd. 3
  4. 4. http://pycon.jp/ 4
  5. 5. 5
  6. 6. Do you know the docstring? 6
  7. 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. 8. Have you written API docs using docstrings? 8
  9. 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. 10. Goal of this session  How to generate a doc from Python source code.  re-discovering the meaning of docstrings. 10
  11. 11. 11
  12. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 23
  24. 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. 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. 26. $ cd doc $ make html ... Build finished. The HTML pages are in _build/html. make html 26
  27. 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. 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. 29. Take care! Sphinx autodoc import your code to get docstrings. It means autodoc will execute code at module global level. 29
  30. 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. 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. 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. 33. "Oh, I can't understand the type of arguments and meanings even reading this!" 33 Lacking necessary information
  34. 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. 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. 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. 37
  38. 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. 39. Syntax highlighted output $ make html ... rendered doctest block 39
  40. 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
  41. 41.  ̄\_(ツ)_/ ̄ 41
  42. 42. doctest builder 42
  43. 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. 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. 45
  46. 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. 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
  48. 48.  ̄\_(ツ)_/ ̄ 48
  49. 49. autosummary extension 49
  50. 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. 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. 52. Output of autosummary autosummary directive become TOC for each module pages. 52
  53. 53. 53
  54. 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
  55. 55. coverage extension 55
  56. 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. 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. 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. 59. Let's make Pull-Request! We are waiting for your contribution to solve the problem. (bow) 59
  60. 60. 60
  61. 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. 62
  63. 63. 1. Options 63
  64. 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. 65. 2. Directives for Web API sphinxcontrib-httpdomain 65
  66. 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. 67. 3. Directives for Diagram sphinxcontrib-blockdiag sphinxcontrib-sqdiag sphinxcontrib-actdiag sphinxcontrib-nwdiag 67
  68. 68. blockdiag series 68 http://blockdiag.com/ blockdiag seqdiag (sequence) actdiag (activity) nwdiag (network) packetdiag (packet) is included in nwdiag
  69. 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
  70. 70. 4. Document translation 70
  71. 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
  72. 72. Questions? @shimizukawa Grab me after the session :) 72
  73. 73. Thanks :) 73
  • helbermg

    Sep. 27, 2015
  • cadu_leite

    Sep. 27, 2015
  • shimabukuro

    Sep. 23, 2015
  • ToshiyukiSakurai

    Aug. 23, 2015
  • KanSakamoto

    Aug. 22, 2015

Using the automated documentation feature of Sphinx, you can make with ease the extensive documentation of Python program. You just write python function documents (docstrings), Sphinx organizes them into the document, can be converted to a variety of formats. In this session, I'll explain a documentation procedure that uses with sphinx autodoc and autosummary extensions.

Views

Total views

2,177

On Slideshare

0

From embeds

0

Number of embeds

226

Actions

Downloads

4

Shares

0

Comments

0

Likes

5

×