Introduction to Python DocumentationRelease v0.0.1

M.Faisal Junaid Butt

August 18, 2015

Contents

1 Models 3

2 Auto Generated Documentation 5

3 Hello World Program Documentation 9

4 Practice 11

5 Indices and tables 15

Bibliography 17

Python Module Index 19

i

ii

Introduction to Python Documentation, Release v0.0.1

Contents:

Contents 1

Introduction to Python Documentation, Release v0.0.1

2 Contents

CHAPTER 1

Models

• Hello Welcome to Python Documentation

3

Introduction to Python Documentation, Release v0.0.1

4 Chapter 1. Models

CHAPTER 2

Auto Generated Documentation

class models.MainClass1This class docstring shows how to use sphinx and rst syntax

The first line is brief explanation, which may be completed with a longer one. For instance to discuss about itsmethods. The only method here is function1()‘s. The main idea is to document the class and methods’sarguments with

•parameters, types, return and return types:

:param arg1: description:param arg2: description:type arg1: type description:type arg1: type description:return: return description:rtype: the return type description

•and to provide sections such as Example using the double commas syntax:

:Example:

followed by a blank line !

which appears as follow:

Example

followed by a blank line

•Finally special sections such as See Also, Warnings, Notes use the sphinx syntax (paragraph directives):

.. seealso:: blabla

.. warnings also:: blabla

.. note:: blabla

.. todo:: blabla

Note:There are many other Info fields but they may be redundant:

• param, parameter, arg, argument, key, keyword: Description of a parameter.

• type: Type of a parameter.

• raises, raise, except, exception: That (and when) a specific exception is raised.

• var, ivar, cvar: Description of a variable.

5

Introduction to Python Documentation, Release v0.0.1

• returns, return: Description of the return value.

• rtype: Return type.

Note: There are many other directives such as versionadded, versionchanged, rubric, centered, ... See thesphinx documentation for more details.

Here below is the results of the function1() docstring.

models.function1(self, arg1, arg2, arg3)returns (arg1 / arg2) + arg3

This is a longer explanation, which may include math with latex syntax . Then, you need to provide optionalsubsection in this order (just to be consistent and have a uniform documentation. Nothing prevent you to switchthe order):

•parameters using :param <name>: <description>

•type of the parameters :type <name>: <description>

•returns using :returns: <description>

•examples (doctest)

•seealso using .. seealso:: text

•notes using .. note:: text

•warning using .. warning:: text

•todo .. todo:: text

Advantages:

• Uses sphinx markups, which will certainly be improved in future version

• Nice HTML output with the See Also, Note, Warnings directives

Drawbacks:

• Just looking at the docstring, the parameter, type and return sections do not appear nicely

Parameters

• arg1 (int, float,...) – the first value

• arg2 (int, float,...) – the first value

• arg3 (int, float,...) – the first value

Returns arg1/arg2 +arg3

Return type int, float

Example

>>> import template>>> a = template.MainClass1()>>> a.function1(1,1,1)2

Note: can be useful to emphasize important feature

6 Chapter 2. Auto Generated Documentation

Introduction to Python Documentation, Release v0.0.1

See also:

MainClass2

Warning: arg2 must be non-zero.

7

Introduction to Python Documentation, Release v0.0.1

8 Chapter 2. Auto Generated Documentation

CHAPTER 3

Hello World Program Documentation

helloworld.welcomeMessage()This function will print the Hello World to the Console

Argument This function will not take any argument

9

Introduction to Python Documentation, Release v0.0.1

10 Chapter 3. Hello World Program Documentation

CHAPTER 4

Practice

Author M.Faisal Junaid Butt

Data 28-07-2015

class practice.myPractice

The example below illustrate the simple table

Note: This Documentation is created by M.Faisal Junaid Butt.

Header row, column 1 Header 2 Header 3body row 1, column 1 column 2 column 3body row 2 Cells may span columns

—long opt and long desc

emphasis

Strong Emphasis

‘interpreted text’

‘’inline literal’‘

*escape*, **escape**

A backlash literal:

The First Para graph

The Second Paragraph

•Enumerated Lists

11

Introduction to Python Documentation, Release v0.0.1

•Bullet Lists

•Definition Lists

•Option Lists

3.The First Item

4.The Second Item

5.The Third Item

•This is Item one

•This is Item two

•“-”, “*” or “+”. continuing text must be aligned

Two Blank lines will be required

Python Python is a programming language.

reStructuredText reStructuredText is a markup syntax and parser system.

•Literal Blocks

•Line Blocks

•Block Quote

•Doctest Block

A Literal Block:

Everything will bekept here.

Out of the literal block.

A Literal Block:

Everything will bekept here.

Out of the literal block

Line Breaks andinitial indents

are preserved

Block Quote are just: Indented Paragraph.

Warning: This Documentation is created by M.Faisal Junaid Butt.

Footnotes:

• Numerical Footnote

• Symbol Footnote

12 Chapter 4. Practice

Introduction to Python Documentation, Release v0.0.1

Note: This Documentation is created by M.Faisal Junaid Butt.

PyHUG 1 and Taipei.py 2 are both the Python user groups in Taiwan.

PyHUG 3 and Taipei.py 4 are both the Python user groups in Taiwan.

Note: This Documentation is created by M.Faisal Junaid Butt.

PyHUG 5 and Taipei.py 6 are both the Python user groups in Taiwan.

Note: This Documentation is created by M.Faisal Junaid Butt.

[PyHUG] and [Taipei.py] are both the Python user groups in Taiwan.

•External

•Internal

•Indirect

•Implicit

PyHUG_ and Taipei.py_ are both the Python user groups in Taiwan.

The Internal HyperLink Target are given below

Note: This Documentation is created by M.Faisal Junaid Butt.

PyHUG_ and Taipei.py_ are both the Python user groups in Taiwan.

Comment: PyHUG and Taipei.py are both the Python user groups in Taiwan.

Images:

• Screen Shots can be added in the documentation

• Logo can be added to the documentation

• The Example is given below

1 http://www.meetup.com/pythonhug/2 http://taipei.python.org.tw/3 http://www.meetup.com/pythonhug/4 http://taipei.python.org.tw/5 http://www.meetup.com/pythonhug/6 http://taipei.python.org.tw/

13

Introduction to Python Documentation, Release v0.0.1

_static.jpg

14 Chapter 4. Practice

CHAPTER 5

Indices and tables

• genindex

• modindex

• search

15

Introduction to Python Documentation, Release v0.0.1

16 Chapter 5. Indices and tables

Bibliography

[PyHUG] http://www.meetup.com/pythonhug/

[Taipei.py] http://taipei.python.org.tw/

17

Introduction to Python Documentation, Release v0.0.1

18 Bibliography

Python Module Index

hhelloworld, 9

mmodels, 5

ppractice, 11

19

Introduction to Python Documentation, Release v0.0.1

20 Python Module Index

Index

Ffunction1() (in module models), 6

Hhelloworld (module), 9

MMainClass1 (class in models), 5models (module), 5myPractice (class in practice), 11

Ppractice (module), 11

WwelcomeMessage() (in module helloworld), 9

21