Pythonドキュメント（：obj： `str`）vs（文字列）

このExample Google Style Python Docstringsドキュメントを読んで、Pythonのドキュメントがどの程度うまく書かれているかを理解しています。しかし、私は一つのことを理解できません。Pythonドキュメント（：obj： `str`）vs（文字列）

文字列を文書化するときに、この奇妙な表記があります。例えば

引数を文書化する場合、ドキュメントは、それらが同じように書くこと指定：

Args: 
    arg1(str): The description for arg1

しかし、いくつかの他の場所で、ドキュメントのようなものが書いている：、後者の場合は

Args: 
    param2 (:obj:`str`, optional): The second parameter.

をなぜ文字列は:obj:`str`と表され、単なる平文ではありませんstr？なぜ最初にstringsの2つの表現がありますか？どちらを使うのですか？

2016-08-16 ironstein

基準が定められていないので。 2番目のオプションは[sphinx-style annotations]（http://www.sphinx-doc.org）を使用するように見えます。 –

あなたが見つけたその文書がすばらしくないことは確かです。それが内部的に矛盾するときではない。 –

@MartijnPietersより優れたドキュメントを教えてください。 – ironstein

あなたの質問に対する答えはPython: Journey from Novice to Expertで与えられると思います。どうやら、:obj:strと書くと、Sphinxのドキュメントには標準のPythonドキュメントのstrオブジェクトへのリンクが含まれているようです。

ところで、この表記は文字列に限定されません。 Example Google Style Python DocstringsでExampleErrorクラスのドキュメンテーション文字列では、それは言う：

Args: 
    msg (str): Human readable string describing the exception. 
    code (:obj:`int`, optional): Error code.

2017-09-28 09:44:28 user1919235

答えて