SlideShare a Scribd company logo
1 of 13
Download to read offline
doctest
Jenny JS Liang (jsliang)
PyConTW 2013
It all began with MoSQL…(thank you
Mosky!)
● http://mosql.mosky.tw/
● 2013年的春節,我在GitHub上看到
Mosky開始著手進行MoSQL……
● 3月的Taipei.py聚會,我問 Mosky:「為
什麼妳的MoSQL文件可以寫得這麼
快?」
● Mosky:「因為我用doctest +
Sphinx!」
A simple sample…
# add.py
def add(a, b):
"""
This is an addition function.
>>> add(1,2)
3
>>> add("Hello", "World")
'HelloWorld'
"""
return a+b
$ python -m doctest -v add.py
Trying:
add(1,2)
Expecting:
3
ok
…
1 items passed all tests:
2 tests in add.add
2 tests in 2 items.
2 passed and 0 failed.
Test passed.
Multilines
# multilines.py
def multilines(input_str):
"""
>>> input_str = '''1st
... 2nd
... 3rd'''
>>> multilines(input_str)
1st
2nd
3rd
"""
print input_str
$ python -m doctest -v 
multilines.py
Trying:
input_str = '''1st
2nd
3rd'''
Expecting nothing
ok
Trying:
prnt_multilines(input_str)
...
Test passed.
Handling blank lines…
# blank.py
def blankline(line1, line2):
"""
Print "line1nnline2".
>>> blankline("Hello", "World")
Hello
<BLANKLINE>
World
"""
print line1
print ""
print line2
$ python -m doctest -v 
blank.py
Trying:
blankline("Hello", "World")
Expecting:
Hello
<BLANKLINE>
World
ok
...
Test passed.
Checking Examples in Docstrings
End your module with the following code:
if __name__ == "__main__":
import doctest
doctest.testmod()
and execute:
$ python <module_name>.py
Autodocumenting
with Sphinx
[PyConTW 2013] doctest
Module Structure
● mymodule/
○ __init__.py
○ add.py
○ blank.py
○ multilines.py
Make sure mymodule is accessible:
$ export PYTHONPATH=$PYTHONPATH:
/path/to/
mymodule
Modify index.rst (use ReST)
Welcome to mymodule's documentation!
====================================
.. toctree::
:maxdepth: 2
.. automodule:: mymodule.add
:members:
.. automodule:: mymodule.blank
:members:
Generating documentation with
Sphinx
1. $ pip install sphinx
2. $ sphinx-quickstart
3. Follow the instructions. When you see
Please indicate if you want to use one of the
following Sphinx extensions:
> autodoc: automatically insert
docstrings from modules (y/N) [n]: y
select "y"!
4. modify index.rst (see the previous slide)
5. $ make html
More information of Sphinx...
● Sphinx http://sphinx-doc.org/
● reStructuredText http://docutils.sourceforge.
net/rst.html
● sphinx.ext.autodoc – Include documentation
from docstrings http://sphinx-doc.
org/ext/autodoc.html
○ .. automodule::
○ .. autoclass::
○ .. autoexception::
○ ...
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 documentation
from docstrings
○ http://sphinx-doc.org/ext/autodoc.html
● Minimal Sphinx setup for autodocumenting
Python modules
○ http://scienceoss.com/minimal-sphinx-setup-for-
autodocumenting-python-modules/

More Related Content

Viewers also liked

影像好日子隨手拍
影像好日子隨手拍 影像好日子隨手拍
影像好日子隨手拍 小華 黃
 
Time Series Estimation of Gas Furnace Data in IMPL and CPLEX Industrial Model...
Time Series Estimation of Gas Furnace Data in IMPL and CPLEX Industrial Model...Time Series Estimation of Gas Furnace Data in IMPL and CPLEX Industrial Model...
Time Series Estimation of Gas Furnace Data in IMPL and CPLEX Industrial Model...Alkis Vazacopoulos
 
Презентація команди Васильківського НВК № 4
Презентація команди Васильківського НВК № 4Презентація команди Васильківського НВК № 4
Презентація команди Васильківського НВК № 408600 Vasilkov
 
Emerging Mobile Trends & Behaviors for 2013
Emerging Mobile Trends & Behaviors for 2013Emerging Mobile Trends & Behaviors for 2013
Emerging Mobile Trends & Behaviors for 2013Paul Booth
 
Human Development
Human DevelopmentHuman Development
Human DevelopmentEnival
 
Gcse sci-f-b1
Gcse sci-f-b1Gcse sci-f-b1
Gcse sci-f-b1opsonise
 
Three point bend deflector slide presentation
Three point bend deflector slide presentationThree point bend deflector slide presentation
Three point bend deflector slide presentationschomp
 
Arthst2 mat techniques_porcelainlacqueredwood_final
Arthst2 mat techniques_porcelainlacqueredwood_finalArthst2 mat techniques_porcelainlacqueredwood_final
Arthst2 mat techniques_porcelainlacqueredwood_finalall_abby
 
Improve Yield Accounting by including Density Measurements Explicitly
Improve Yield Accounting by including Density Measurements ExplicitlyImprove Yield Accounting by including Density Measurements Explicitly
Improve Yield Accounting by including Density Measurements ExplicitlyAlkis Vazacopoulos
 
Thong diep cho cuoc song
Thong diep cho cuoc songThong diep cho cuoc song
Thong diep cho cuoc songlethao1491
 
Karate Training in Universal City
Karate Training in Universal CityKarate Training in Universal City
Karate Training in Universal Citykaratedojo2
 
Latihan bab6 cikgugeog
Latihan bab6 cikgugeogLatihan bab6 cikgugeog
Latihan bab6 cikgugeogKila Shakila
 

Viewers also liked (20)

影像好日子隨手拍
影像好日子隨手拍 影像好日子隨手拍
影像好日子隨手拍
 
Time Series Estimation of Gas Furnace Data in IMPL and CPLEX Industrial Model...
Time Series Estimation of Gas Furnace Data in IMPL and CPLEX Industrial Model...Time Series Estimation of Gas Furnace Data in IMPL and CPLEX Industrial Model...
Time Series Estimation of Gas Furnace Data in IMPL and CPLEX Industrial Model...
 
Dsl public
Dsl publicDsl public
Dsl public
 
Intropdf
IntropdfIntropdf
Intropdf
 
Презентація команди Васильківського НВК № 4
Презентація команди Васильківського НВК № 4Презентація команди Васильківського НВК № 4
Презентація команди Васильківського НВК № 4
 
Emerging Mobile Trends & Behaviors for 2013
Emerging Mobile Trends & Behaviors for 2013Emerging Mobile Trends & Behaviors for 2013
Emerging Mobile Trends & Behaviors for 2013
 
Human Development
Human DevelopmentHuman Development
Human Development
 
Mem bhee1
Mem bhee1Mem bhee1
Mem bhee1
 
Big europian cities
Big europian citiesBig europian cities
Big europian cities
 
Gcse sci-f-b1
Gcse sci-f-b1Gcse sci-f-b1
Gcse sci-f-b1
 
Manual arranque dual
Manual arranque dualManual arranque dual
Manual arranque dual
 
Three point bend deflector slide presentation
Three point bend deflector slide presentationThree point bend deflector slide presentation
Three point bend deflector slide presentation
 
Arthst2 mat techniques_porcelainlacqueredwood_final
Arthst2 mat techniques_porcelainlacqueredwood_finalArthst2 mat techniques_porcelainlacqueredwood_final
Arthst2 mat techniques_porcelainlacqueredwood_final
 
Af cat agricola
Af cat agricolaAf cat agricola
Af cat agricola
 
Improve Yield Accounting by including Density Measurements Explicitly
Improve Yield Accounting by including Density Measurements ExplicitlyImprove Yield Accounting by including Density Measurements Explicitly
Improve Yield Accounting by including Density Measurements Explicitly
 
Thong diep cho cuoc song
Thong diep cho cuoc songThong diep cho cuoc song
Thong diep cho cuoc song
 
Karate Training in Universal City
Karate Training in Universal CityKarate Training in Universal City
Karate Training in Universal City
 
4524
45244524
4524
 
El eclipse
El eclipseEl eclipse
El eclipse
 
Latihan bab6 cikgugeog
Latihan bab6 cikgugeogLatihan bab6 cikgugeog
Latihan bab6 cikgugeog
 

Similar to [PyConTW 2013] doctest

Writing Commits for You, Your Friends, and Your Future Self
Writing Commits for You, Your Friends, and Your Future SelfWriting Commits for You, Your Friends, and Your Future Self
Writing Commits for You, Your Friends, and Your Future SelfAll Things Open
 
Test First Teaching
Test First TeachingTest First Teaching
Test First TeachingSarah Allen
 
Lecture for Bootstrap and flask in Python
Lecture for Bootstrap and flask in PythonLecture for Bootstrap and flask in Python
Lecture for Bootstrap and flask in PythonNaoki Watanabe
 
QA Fest 2015. Яков Крамаренко. Polyglot automation
QA Fest 2015. Яков Крамаренко. Polyglot automation QA Fest 2015. Яков Крамаренко. Polyglot automation
QA Fest 2015. Яков Крамаренко. Polyglot automation QAFest
 
Polyglot automation - QA Fest - 2015
Polyglot automation - QA Fest - 2015Polyglot automation - QA Fest - 2015
Polyglot automation - QA Fest - 2015Iakiv Kramarenko
 
ES3-2020-P3 TDD Calculator
ES3-2020-P3 TDD CalculatorES3-2020-P3 TDD Calculator
ES3-2020-P3 TDD CalculatorDavid Rodenas
 
node.js, javascript and the future
node.js, javascript and the futurenode.js, javascript and the future
node.js, javascript and the futureJeff Miccolis
 
Joker'15 Java straitjackets for MongoDB
Joker'15 Java straitjackets for MongoDBJoker'15 Java straitjackets for MongoDB
Joker'15 Java straitjackets for MongoDBAlexey Zinoviev
 
From Java to Kotlin - The first month in practice
From Java to Kotlin - The first month in practiceFrom Java to Kotlin - The first month in practice
From Java to Kotlin - The first month in practiceStefanTomm
 
Test First Teaching and the path to TDD
Test First Teaching and the path to TDDTest First Teaching and the path to TDD
Test First Teaching and the path to TDDSarah Allen
 
Data processing with celery and rabbit mq
Data processing with celery and rabbit mqData processing with celery and rabbit mq
Data processing with celery and rabbit mqJeff Peck
 
Intro to JavaScript Testing
Intro to JavaScript TestingIntro to JavaScript Testing
Intro to JavaScript TestingRan Mizrahi
 
Nodejs functions & modules
Nodejs functions & modulesNodejs functions & modules
Nodejs functions & modulesmonikadeshmane
 
Node.js - JavaScript Chicago Meetup
Node.js - JavaScript Chicago MeetupNode.js - JavaScript Chicago Meetup
Node.js - JavaScript Chicago Meetuphugs
 

Similar to [PyConTW 2013] doctest (20)

Writing Commits for You, Your Friends, and Your Future Self
Writing Commits for You, Your Friends, and Your Future SelfWriting Commits for You, Your Friends, and Your Future Self
Writing Commits for You, Your Friends, and Your Future Self
 
Easy automation.py
Easy automation.pyEasy automation.py
Easy automation.py
 
Test First Teaching
Test First TeachingTest First Teaching
Test First Teaching
 
Lecture for Bootstrap and flask in Python
Lecture for Bootstrap and flask in PythonLecture for Bootstrap and flask in Python
Lecture for Bootstrap and flask in Python
 
Spock
SpockSpock
Spock
 
QA Fest 2015. Яков Крамаренко. Polyglot automation
QA Fest 2015. Яков Крамаренко. Polyglot automation QA Fest 2015. Яков Крамаренко. Polyglot automation
QA Fest 2015. Яков Крамаренко. Polyglot automation
 
Polyglot automation - QA Fest - 2015
Polyglot automation - QA Fest - 2015Polyglot automation - QA Fest - 2015
Polyglot automation - QA Fest - 2015
 
ES3-2020-P3 TDD Calculator
ES3-2020-P3 TDD CalculatorES3-2020-P3 TDD Calculator
ES3-2020-P3 TDD Calculator
 
node.js, javascript and the future
node.js, javascript and the futurenode.js, javascript and the future
node.js, javascript and the future
 
Database connectivity in python
Database connectivity in pythonDatabase connectivity in python
Database connectivity in python
 
Joker'15 Java straitjackets for MongoDB
Joker'15 Java straitjackets for MongoDBJoker'15 Java straitjackets for MongoDB
Joker'15 Java straitjackets for MongoDB
 
Testing with PostgreSQL
Testing with PostgreSQLTesting with PostgreSQL
Testing with PostgreSQL
 
50 Ways To Love Your Project
50 Ways To Love Your Project50 Ways To Love Your Project
50 Ways To Love Your Project
 
From Java to Kotlin - The first month in practice
From Java to Kotlin - The first month in practiceFrom Java to Kotlin - The first month in practice
From Java to Kotlin - The first month in practice
 
Test First Teaching and the path to TDD
Test First Teaching and the path to TDDTest First Teaching and the path to TDD
Test First Teaching and the path to TDD
 
Data processing with celery and rabbit mq
Data processing with celery and rabbit mqData processing with celery and rabbit mq
Data processing with celery and rabbit mq
 
Intro to JavaScript Testing
Intro to JavaScript TestingIntro to JavaScript Testing
Intro to JavaScript Testing
 
Nodejs functions & modules
Nodejs functions & modulesNodejs functions & modules
Nodejs functions & modules
 
Node.js - JavaScript Chicago Meetup
Node.js - JavaScript Chicago MeetupNode.js - JavaScript Chicago Meetup
Node.js - JavaScript Chicago Meetup
 
Lightning talk- testing
Lightning talk- testingLightning talk- testing
Lightning talk- testing
 

Recently uploaded

20230202 - Introduction to tis-py
20230202 - Introduction to tis-py20230202 - Introduction to tis-py
20230202 - Introduction to tis-pyJamie (Taka) Wang
 
Videogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfVideogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfinfogdgmi
 
Empowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership BlueprintEmpowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership BlueprintMahmoud Rabie
 
Comparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and IstioComparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and IstioChristian Posta
 
COMPUTER 10: Lesson 7 - File Storage and Online Collaboration
COMPUTER 10: Lesson 7 - File Storage and Online CollaborationCOMPUTER 10: Lesson 7 - File Storage and Online Collaboration
COMPUTER 10: Lesson 7 - File Storage and Online Collaborationbruanjhuli
 
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfJamie (Taka) Wang
 
Introduction to Matsuo Laboratory (ENG).pptx
Introduction to Matsuo Laboratory (ENG).pptxIntroduction to Matsuo Laboratory (ENG).pptx
Introduction to Matsuo Laboratory (ENG).pptxMatsuo Lab
 
Designing A Time bound resource download URL
Designing A Time bound resource download URLDesigning A Time bound resource download URL
Designing A Time bound resource download URLRuncy Oommen
 
Machine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfMachine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfAijun Zhang
 
Building AI-Driven Apps Using Semantic Kernel.pptx
Building AI-Driven Apps Using Semantic Kernel.pptxBuilding AI-Driven Apps Using Semantic Kernel.pptx
Building AI-Driven Apps Using Semantic Kernel.pptxUdaiappa Ramachandran
 
Bird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystemBird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystemAsko Soukka
 
Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024D Cloud Solutions
 
Building Your Own AI Instance (TBLC AI )
Building Your Own AI Instance (TBLC AI )Building Your Own AI Instance (TBLC AI )
Building Your Own AI Instance (TBLC AI )Brian Pichman
 
Igniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration WorkflowsIgniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration WorkflowsSafe Software
 
OpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureOpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureEric D. Schabell
 
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfIaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfDaniel Santiago Silva Capera
 
UiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPathCommunity
 

Recently uploaded (20)

20230202 - Introduction to tis-py
20230202 - Introduction to tis-py20230202 - Introduction to tis-py
20230202 - Introduction to tis-py
 
Videogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfVideogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdf
 
Empowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership BlueprintEmpowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership Blueprint
 
Comparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and IstioComparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and Istio
 
20230104 - machine vision
20230104 - machine vision20230104 - machine vision
20230104 - machine vision
 
COMPUTER 10: Lesson 7 - File Storage and Online Collaboration
COMPUTER 10: Lesson 7 - File Storage and Online CollaborationCOMPUTER 10: Lesson 7 - File Storage and Online Collaboration
COMPUTER 10: Lesson 7 - File Storage and Online Collaboration
 
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
 
Introduction to Matsuo Laboratory (ENG).pptx
Introduction to Matsuo Laboratory (ENG).pptxIntroduction to Matsuo Laboratory (ENG).pptx
Introduction to Matsuo Laboratory (ENG).pptx
 
Designing A Time bound resource download URL
Designing A Time bound resource download URLDesigning A Time bound resource download URL
Designing A Time bound resource download URL
 
Machine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfMachine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdf
 
Building AI-Driven Apps Using Semantic Kernel.pptx
Building AI-Driven Apps Using Semantic Kernel.pptxBuilding AI-Driven Apps Using Semantic Kernel.pptx
Building AI-Driven Apps Using Semantic Kernel.pptx
 
Bird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystemBird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystem
 
Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024
 
Building Your Own AI Instance (TBLC AI )
Building Your Own AI Instance (TBLC AI )Building Your Own AI Instance (TBLC AI )
Building Your Own AI Instance (TBLC AI )
 
Igniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration WorkflowsIgniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration Workflows
 
OpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureOpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability Adventure
 
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfIaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
 
20150722 - AGV
20150722 - AGV20150722 - AGV
20150722 - AGV
 
201610817 - edge part1
201610817 - edge part1201610817 - edge part1
201610817 - edge part1
 
UiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation Developers
 

[PyConTW 2013] doctest

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