Think about the format of your data structures, especially for extendible ones. For example:
# This works. spam = ['i', 'hate', 'spam'] # But this is much better. eggs = [ 'i', 'like', 'eggs', ]
If you’re expanding both lists and you make a
diff, you’ll notice that the changes of
spam are much harder to tell than the changes of
Therefor prefer the multi- over the single-line format. Also make sure you always add a trailing comma to the last element as well.
Here’s an example:
def spam(eggs): ''' Add SPAM to ``eggs``. :param str eggs: The eggs :return: The eggs with SPAM :rtype: str ''' return eggs ' with SPAM'
Cross-referencing should also be made with the Sphinx Python domain notation, for example:
def spam(): ''' Provides SPAM. .. seealso:: :py:meth:`spam.eggs.Egg.boil` The method used to boil eggs. '''