Skip to main content
`Ctrl`+`K`

# format_doc

astropy.utils.decorators.format_doc(docstring, *args, **kwargs)

  Replaces the docstring of the decorated object and then formats it.

  The formatting works like `str.format()` and if the decorated object already has a docstring this docstring can be included in the new documentation if you use the `{__doc__}` placeholder. Its primary use is for reusing a long docstring in multiple functions when it is the same or only slightly different between them.

  Parameters:
    docstring `python:str` or `object` or `python:None`

      The docstring that will replace the docstring of the decorated object. If it is an object like a function or class it will take the docstring of this object. If it is a string it will use the string itself. One special case is if the string is `None` then it will use the decorated functions docstring and formats it.

    args

      passed to `str.format()`.

    kwargs

      passed to `str.format()`. If the function has a (not empty) docstring the original docstring is added to the kwargs with the keyword `'__doc__'`.

  Raises:
    `ValueError`

      If the `docstring` (or interpreted docstring if it was `None` or not a string) is empty.

    `IndexError`, `KeyError`

      If a placeholder in the (interpreted) `docstring` was not filled. see `str.format()` for more information.

  Notes

  Using this decorator allows, for example Sphinx, to parse the correct docstring.

  Examples

  Replacing the current docstring is very easy:

      >>> from astropy.utils.decorators import format_doc
      >>> @format_doc('''Perform num1 + num2''')
      ... def add(num1, num2):
      ...     return num1+num2
      ...
      >>> help(add)
      Help on function add in module __main__:

      add(num1, num2)
          Perform num1 + num2

  sometimes instead of replacing you only want to add to it:

      >>> doc = '''
      ...       {__doc__}
      ...       Parameters
      ...       ----------
      ...       num1, num2 : Numbers
      ...       Returns
      ...       -------
      ...       result: Number
      ...       '''
      >>> @format_doc(doc)
      ... def add(num1, num2):
      ...     '''Perform addition.'''
      ...     return num1+num2
      ...
      >>> help(add)
      Help on function add in module __main__:

      add(num1, num2)
          Perform addition.
          Parameters
          ----------
          num1, num2 : Numbers
          Returns
          -------
          result : Number

  in case one might want to format it further:

      >>> doc = '''
      ...       Perform {0}.
      ...       Parameters
      ...       ----------
      ...       num1, num2 : Numbers
      ...       Returns
      ...       -------
      ...       result: Number
      ...           result of num1 {op} num2
      ...       {__doc__}
      ...       '''
      >>> @format_doc(doc, 'addition', op='+')
      ... def add(num1, num2):
      ...     return num1+num2
      ...
      >>> @format_doc(doc, 'subtraction', op='-')
      ... def subtract(num1, num2):
      ...     '''Notes: This one has additional notes.'''
      ...     return num1-num2
      ...
      >>> help(add)
      Help on function add in module __main__:

      add(num1, num2)
          Perform addition.
          Parameters
          ----------
          num1, num2 : Numbers
          Returns
          -------
          result : Number
              result of num1 + num2
      >>> help(subtract)
      Help on function subtract in module __main__:

      subtract(num1, num2)
          Perform subtraction.
          Parameters
          ----------
          num1, num2 : Numbers
          Returns
          -------
          result : Number
              result of num1 - num2
          Notes : This one has additional notes.

  These methods can be combined; even taking the docstring from another object is possible as docstring attribute. You just have to specify the object:

      >>> @format_doc(add)
      ... def another_add(num1, num2):
      ...     return num1 + num2
      ...
      >>> help(another_add)
      Help on function another_add in module __main__:

      another_add(num1, num2)
          Perform addition.
          Parameters
          ----------
          num1, num2 : Numbers
          Returns
          -------
          result : Number
              result of num1 + num2

  But be aware that this decorator only formats the given docstring not the strings passed as `args` or `kwargs` (not even the original docstring):

      >>> @format_doc(doc, 'addition', op='+')
      ... def yet_another_add(num1, num2):
      ...    '''This one is good for {0}.'''
      ...    return num1 + num2
      ...
      >>> help(yet_another_add)
      Help on function yet_another_add in module __main__:

      yet_another_add(num1, num2)
          Perform addition.
          Parameters
          ----------
          num1, num2 : Numbers
          Returns
          -------
          result : Number
              result of num1 + num2
          This one is good for {0}.

  To work around it you could specify the docstring to be `None`:

      >>> @format_doc(None, 'addition')
      ... def last_add_i_swear(num1, num2):
      ...    '''This one is good for {0}.'''
      ...    return num1 + num2
      ...
      >>> help(last_add_i_swear)
      Help on function last_add_i_swear in module __main__:

      last_add_i_swear(num1, num2)
          This one is good for addition.

  Using it with `None` as docstring allows to use the decorator twice on an object to first parse the new docstring and then to parse the original docstring or the `args` and `kwargs`.