[零基礎學python]Python文檔

文檔，這個詞語在常常在程序員的嘴裏冒出來，有時候他們還常常以文檔有沒有或者全不全爲標準來衡量一個軟件項目是否高大上。那麼，軟件中的文檔是什麼呢？有什麼要求呢？python文檔又是什麼呢？文檔有什麼用呢？

文檔很重要。獨孤九劍的劍訣、易筋經的心法、寫着辟邪劍譜的袈裟，這些都是文檔。連那些大牛人都要這些文檔，更況且咱們呢？因此，文檔是很重要的。

文檔，說白了就是用word（這個最多了）等（注意這裏的等，把不經常使用的工具都等掉了，包括我編輯文本時用的vim工具）文本編寫工具寫成的包含文本內容但不限於文字的文件。有點囉嗦，囉嗦的目的是爲了嚴謹，呵呵。最好仍是來一個更讓人信服的定義，固然是來自維基百科。

軟件文檔或者源代碼文檔是指與軟件系統及其軟件工程過程有關聯的文本實體。文檔的類型包括軟件需求文檔，設計文檔，測試文檔，用戶手冊等。其中的需求文檔，設計文檔和測試文檔通常是在軟件開發過程當中由開發者寫就的，而用戶手冊等非過程類文檔是由專門的非技術類寫做人員寫就的。

早期的軟件文檔主要指的是用戶手冊，根據Barker的定義，文檔是用來對軟件系統界面元素的設計、規劃和實現過程的記錄，以此來加強系統的可用性。而Forward則認爲軟件文檔是被軟件工程師之間用做溝通交流的一種方式，溝通的信息主要是有關所開發的軟件系統。Parnas則強調文檔的權威性，他認爲文檔應該提供對軟件系統的精確描述。

綜上，咱們能夠將軟件文檔定義爲：

1.文檔是一種對軟件系統的書面描述；
2.文檔應當精確地描述軟件系統；
3.軟件文檔是軟件工程師之間用做溝通交流的一種方式；
4.文檔的類型有不少種，包括軟件需求文檔，設計文檔，測試文檔，用戶手冊等；
5.文檔的呈現方式有不少種，能夠是傳統的書面文字形式或圖表形式，也但是動態的網頁形式

那麼這裏說的Python文檔指的是什麼呢？一個方面就是每一個學習者要學習python，python的開發者們（他們都是大牛）給咱們這些小白提供了什麼東西沒有？可以讓咱們給他們這些大牛溝通，理解python中每一個函數、指令等的含義和用法呢？

有。大牛就是大牛，他們準備了，並且還不止一個。

查看python文檔

真誠的敬告全部看本教程的諸位，要想得到編程上的昇華，看文檔是必須的。文檔賽過了全部的教程和全部的老師以及全部的大牛。爲何呢？其中緣由，都要等待看官看懂了以後，有了體會感悟以後才能明白。

python文檔的網址：https://docs.python.org/2/，這是python2.x，從這裏也能夠找到python3.x的文檔。

除了看網站上的文檔，還有別的方式嗎？

有，並且看官並不陌生，此前已經在本教程中屢次用到，那就是dir()和help()

>>> dir(list)
['__add__', '__class__', '__contains__', '__delattr__', '__delitem__', '__delslice__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__getslice__', '__gt__', '__hash__', '__iadd__', '__imul__', '__init__', '__iter__', '__le__', '__len__', '__lt__', '__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__reversed__', '__rmul__', '__setattr__', '__setitem__', '__setslice__', '__sizeof__', '__str__', '__subclasshook__', 'append', 'count', 'extend', 'index', 'insert', 'pop', 'remove', 'reverse', 'sort']

>>> help(list.__mul__)

Help on wrapper_descriptor:

__mul__(...)
    x.__mul__(n) <==> x*n

這種查看文檔的方式，在交互模式下常常用到，快捷方便，請看官務必牢記並使用。

正如前面已經介紹過的，還有一個文檔：doc,help調用的其實就是這個函數裏面的內容。

>>> print(list.__mul__.__doc__)     #與help(list.__mul__)顯示的內容一致
x.__mul__(n) <==> x*n

>>> print(list.index.__doc__)       #查看index的文檔
L.index(value, [start, [stop]]) -> integer -- return first index of value.
Raises ValueError if the value is not present.

給本身的程序加上文檔

在本身編寫程序的時候，也很是但願可以有相似上面查看python文檔的功能，能夠經過某種方式查看本身的程序文檔，這樣顯得本身多牛呀。

有一種方法能夠實現，就是在你所編寫的程序中用三個雙引號或者單引號成對地出現，中間寫上有關文檔內容。

>>> def qiwsir():
...     """I like python"""
...     print "http://qiwsir.github.io"
... 
>>> qiwsir()
http://qiwsir.github.io

>>> print(qiwsir.__doc__)   #用這種方法能夠看本身寫的函數中的文檔
I like python

>>> help(qiwsir)            #其實就是調用__doc__顯示的內容

Help on function qiwsir in module __main__:

qiwsir()
    I like python

另外，對於一個文件，能夠把有關說明放在文件的前面，不影響該文件代碼運行。

例如，有這樣一個擴展名是.py的python文件，其內容是：

#!/usr/bin/env python
#coding:utf-8

import random

number = random.randint(1,100)

guess = 0

while True:

    num_input = raw_input("please input one integer that is in 1 to 100:")
    guess +=1

    if not num_input.isdigit():
        print "Please input interger."
    elif int(num_input)<0 and int(num_input)>=100:
        print "The number should be in 1 to 100."
    else:
        if number==int(num_input):
            print "OK, you are good.It is only %d, then you successed."%guess
            break
        elif number>int(num_input):
            print "your number is more less."
        elif number<int(num_input):
            print "your number is bigger."
        else:
            print "There is something bad, I will not work"

這段程序，就是在《用while來循環》中用到的一個猜數字的遊戲，它存儲在名爲205-2.py的文件中，若是要對這段程序寫一個文檔，就能夠這麼作。

"""
   This is a game.
   I am Qiwei.
   I like python.
   I am writing python articles in my website.
   My website is http://qiwsir.github.io
   You can learn python free in it.
"""

#!/usr/bin/env python
#coding:utf-8

import random

number = random.randint(1,100)

guess = 0

while True:

    num_input = raw_input("please input one integer that is in 1 to 100:")
    guess +=1

    if not num_input.isdigit():
        print "Please input interger."
    elif int(num_input)<0 and int(num_input)>=100:
        print "The number should be in 1 to 100."
    else:
        if number==int(num_input):
            print "OK, you are good.It is only %d, then you successed."%guess
            break
        elif number>int(num_input):
            print "your number is more less."
        elif number<int(num_input):
            print "your number is bigger."
        else:
            print "There is something bad, I will not work"

最後，推薦一片至關至關好的文章，與列位分享：

Python 自省指南:如何監視您的 Python 對象