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

Question

I have been reading the this Example Google Style Python Docstrings document to understand how good Python documentation is written. But I can't understand one thing.

When documenting strings, there is this weird notation.

For example when documenting arguments, the documentation specifies they be written like :

Args: 
    arg1(str): The description for arg1

But, in some other places, the document writes something like :

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

In the second case, why is the string represented as :obj:`str` and not just plain str? Why two representations for strings in the first place? When do I use which?

Answer 1

I think that the answer to your question is given in Python: Journey from Novice to Expert. Apparently, if you write :obj:str, your Sphinx documentation will contain a link to the str object in the standard Python documentation.

By the way, this notation is not restricted to strings. In the docstrings of the ExampleError class in Example Google Style Python Docstrings it says:

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