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?

Because there is no standard. The second option appears to use [sphinx-style annotations](http://www.sphinx-doc.org). — Martijn Pieters, Aug 16 '16 at 07:35
I'm not sure that that document you found is all that great; not when it is internally inconsistent like that. — Martijn Pieters, Aug 16 '16 at 07:40
Perhaps http://docs.python-guide.org/en/latest/writing/documentation/; which comes down to 'use Sphinx'. — Martijn Pieters, Aug 16 '16 at 08:07

user1919235 · Answer 1 · 2017-09-28T09:57:27.677

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.

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

1 Answers1

Linked