Python Documentation (: obj :`str`) vs (str)

Question

이 Example Google Style Python Docstrings 문서를 읽고 얼마나 훌륭한 파이썬 문서가 작성되었는지 이해하고 있습니다. 그러나 나는 한 가지를 이해할 수 없다.

문자열을 문서화 할 때 이상한 표기법이 있습니다. , 두 번째 경우

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

: 그러나, 다른 장소에서, 문서 같은 것을 기록

Args: 
    arg1(str): The description for arg1 

: 인수를 문서화 할 때

는 예를 들어, 문서들은이처럼 쓸 수 지정 문자열이 :obj:`str`으로 표시되고 일반 문자가 str이 아닌 이유는 무엇입니까? 왜 strings에 대한 두 가지 표현이 첫 번째 이유입니까? 어떤 것을 사용합니까?

Answer 1

귀하의 질문에 대한 답변은 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.