[PyConTW 2013] doctest

  • 589 views
Uploaded on

 

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads

Views

Total Views
589
On Slideshare
0
From Embeds
0
Number of Embeds
1

Actions

Shares
Downloads
7
Comments
0
Likes
5

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. doctestJenny JS Liang (jsliang)PyConTW 2013
  • 2. It all began with MoSQL…(thank youMosky!)● http://mosql.mosky.tw/● 2013年的春節,我在GitHub上看到Mosky開始著手進行MoSQL……● 3月的Taipei.py聚會,我問 Mosky:「為什麼妳的MoSQL文件可以寫得這麼快?」● Mosky:「因為我用doctest +Sphinx!」
  • 3. A simple sample…# add.pydef add(a, b):"""This is an addition function.>>> add(1,2)3>>> add("Hello", "World")HelloWorld"""return a+b$ python -m doctest -v add.pyTrying:add(1,2)Expecting:3ok…1 items passed all tests:2 tests in add.add2 tests in 2 items.2 passed and 0 failed.Test passed.
  • 4. Multilines# multilines.pydef multilines(input_str):""">>> input_str = 1st... 2nd... 3rd>>> multilines(input_str)1st2nd3rd"""print input_str$ python -m doctest -v multilines.pyTrying:input_str = 1st2nd3rdExpecting nothingokTrying:prnt_multilines(input_str)...Test passed.
  • 5. Handling blank lines…# blank.pydef blankline(line1, line2):"""Print "line1nnline2".>>> blankline("Hello", "World")Hello<BLANKLINE>World"""print line1print ""print line2$ python -m doctest -v blank.pyTrying:blankline("Hello", "World")Expecting:Hello<BLANKLINE>Worldok...Test passed.
  • 6. Checking Examples in DocstringsEnd your module with the following code:if __name__ == "__main__":import doctestdoctest.testmod()and execute:$ python <module_name>.py
  • 7. Autodocumentingwith Sphinx
  • 8. Module Structure● mymodule/○ __init__.py○ add.py○ blank.py○ multilines.pyMake sure mymodule is accessible:$ export PYTHONPATH=$PYTHONPATH:/path/to/mymodule
  • 9. Modify index.rst (use ReST)Welcome to mymodules documentation!====================================.. toctree:::maxdepth: 2.. automodule:: mymodule.add:members:.. automodule:: mymodule.blank:members:
  • 10. Generating documentation withSphinx1. $ pip install sphinx2. $ sphinx-quickstart3. Follow the instructions. When you seePlease indicate if you want to use one of thefollowing Sphinx extensions:> autodoc: automatically insertdocstrings from modules (y/N) [n]: yselect "y"!4. modify index.rst (see the previous slide)5. $ make html
  • 11. More information of Sphinx...● Sphinx http://sphinx-doc.org/● reStructuredText http://docutils.sourceforge.net/rst.html● sphinx.ext.autodoc – Include documentationfrom docstrings http://sphinx-doc.org/ext/autodoc.html○ .. automodule::○ .. autoclass::○ .. autoexception::○ ...
  • 12. References● Python doctest○ http://docs.python.org/3/library/doctest.html● Documenting Your Project Using Sphinx○ http://pythonhosted.org/an_example_pypi_project/sphinx.html● sphinx.ext.autodoc – Include documentationfrom docstrings○ http://sphinx-doc.org/ext/autodoc.html● Minimal Sphinx setup for autodocumentingPython modules○ http://scienceoss.com/minimal-sphinx-setup-for-autodocumenting-python-modules/