Documenting a Python function with docstring, which is read in raw form and provides good sphinx output

Question

I have a Python application. I am using Sphinx with the autodoc extension to generate documents for it. When documenting function arguments, I see two main options:

Option 1

def makeBaby(mommy, daddy):
  """Execute the miracle of life.

  Args:
    mommy: description of mommy
    daddy: description of daddy
  """

Option 2

def makeBaby(mommy, daddy):
  """Execute the miracle of life.

  :param mommy: description of mommy
  :param daddy: description of daddy
  """

, 2 "Args", 1, . 2 , 1, . param ? 1 ( Google Python) -, . docstrings , docstring, ?

Answer 1

docstrings numpy numpydoc, , sphinx.

numpydoc:

pip install numpydoc

'numpydoc' conf.py .

extensions = ['sphinx.ext.autodoc',
              'numpydoc']

docstrings numpy. docs. :

def makeBaby(mommy, daddy):
   """Execute the miracle of life.

   Parameters
   ----------
   mommy : description of mommy
   daddy : description of daddy

   Returns
   -------
   baby : mommy + daddy

   """
   return mommy + daddy

:

Answer 2

, ,

: 2 "Args"

2 - . / .., , Sphinx, . , , 2 ( " , docstring):

.. py:method:: create(**fields)
    :module: redmine.managers.ResourceManager
    :noindex:

    Creates new issue resource with given fields and saves it to the Redmine.

    :param project_id: (required). Id or identifier of issue project.
    :type project_id: integer or string
    :param string subject: (required). Issue subject.
    :param integer tracker_id: (optional). Issue tracker id.
    :param string description: (optional). Issue description.
    :param integer status_id: (optional). Issue status id.
    :param integer priority_id: (optional). Issue priority id.
    :param integer category_id: (optional). Issue category id.
    :param integer fixed_version_id: (optional). Issue version id.
    :param boolean is_private: (optional). Whether issue is private.
    :param integer assigned_to_id: (optional). Issue will be assigned to this user id.
    :param watcher_user_ids: (optional). User ids who will be watching this issue.
    :type watcher_user_ids: list or tuple
    :param integer parent_issue_id: (optional). Parent issue id.
    :param start_date: (optional). Issue start date.
    :type start_date: string or date object
    :param due_date: (optional). Issue end date.
    :type due_date: string or date object
    :param integer estimated_hours: (optional). Issue estimated hours.
    :param integer done_ratio: (optional). Issue done ratio.
    :param list custom_fields: (optional). Custom fields in the form of [{'id': 1, 'value': 'foo'}].
    :param uploads:
      .. raw:: html

          (optional). Uploads in the form of [{'': ''}, ...], accepted keys are:

      - path (required). Absolute path to the file that should be uploaded.
      - filename (optional). Name of the file after upload.
      - description (optional). Description of the file.
      - content_type (optional). Content type of the file.

    :type uploads: list or tuple
    :return: Issue resource object

:

, , , -.