Introduction to Python Documentation

Transcription

1 Introduction to Python Documentation Release v0.0.1 M.Faisal Junaid Butt August 18, 2015

2

3 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

4 ii

5 Contents: Contents 1

6 2 Contents

7 CHAPTER 1 Models Hello Welcome to Python Documentation 3

8 4 Chapter 1. Models

9 CHAPTER 2 Auto Generated Documentation class models.mainclass1 This 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 its methods. The only method here is function1() s. The main idea is to document the class and methods s arguments 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

10 returns, return: Description of the return value. rtype: Return type. Note: There are many other directives such as versionadded, versionchanged, rubric, centered,... See the sphinx 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 optional subsection in this order (just to be consistent and have a uniform documentation. Nothing prevent you to switch the order): parameters using :param <name>: type of the parameters :type <name>: returns using :returns: examples (doctest) <description> seealso using.. seealso:: text notes using.. note:: text warning using.. warning:: text todo.. todo:: text Advantages: Drawbacks: <description> <description> Uses sphinx markups, which will certainly be improved in future version Nice HTML output with the See Also, Note, Warnings directives 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

11 See also: MainClass2 Warning: arg2 must be non-zero. 7

12 8 Chapter 2. Auto Generated Documentation

13 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

14 10 Chapter 3. Hello World Program Documentation

15 CHAPTER 4 Practice Author M.Faisal Junaid Butt Data 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 3 body row 1, column 1 column 2 column 3 body 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

16 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 be kept here. Out of the literal block. A Literal Block: Everything will be kept here. Out of the literal block Line Breaks and initial 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

17 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

18 _static.jpg 14 Chapter 4. Practice

19 CHAPTER 5 Indices and tables genindex modindex search 15

20 16 Chapter 5. Indices and tables

21 Bibliography [PyHUG] [Taipei.py] 17

22 18 Bibliography

23 Python Module Index h helloworld, 9 m models, 5 p practice, 11 19

24 20 Python Module Index

25 Index F function1() (in module models), 6 H helloworld (module), 9 M MainClass1 (class in models), 5 models (module), 5 mypractice (class in practice), 11 P practice (module), 11 W welcomemessage() (in module helloworld), 9 21