Documentation

documentation.md

Some example of a documented function

Check the Sphinx documentation, heavily used within Python. This is a reStructedText doc: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#python-signatures

.. py:function:: send_message(sender, recipient, message_body, [priority=1])

   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring

Option 1 - Rendered in markdown

What would be the minimal change to have it "rendered" properly in markdown? If we prefix with something standard like function we can do all kind of additional parsing on a documentation server to make it look even nicer.

function send_message(sender, recipient, message_body, [priority=1])

Send a message to a recipient

• parameters
  • sender(str): The person sending the message
  • recipient(str): The recipient of the message
  • message_body(str): The body of the message
  • priority(int or None): The priority of the message, can be a number 1-5
• return(int): the message id
• raises
  • ValueError: if the message_body exceeds 160 characters
  • TypeError: if the message_body is not a basestring

Option 2 - Render in markdown and make collapsible

This also renders on github and is collapsible.

send_message(sender, recipient, message_body, [priority=1])

Send a message to a recipient

• parameters
  • sender(str): The person sending the message
  • recipient(str): The recipient of the message
  • message_body(str): The body of the message
  • priority(int or None): The priority of the message, can be a number 1-5
• return(int): the message id
• raises
  • ValueError: if the message_body exceeds 160 characters
  • TypeError: if the message_body is not a basestring

Use this function like this:

send_message('alice','bob','quantum_secret', 1);

Option 3 - Render in markdown, make collapsible, default open

This also renders on github and is collapsible.

send_message(sender, recipient, message_body, [priority=1])

Send a message to a recipient

• parameters
  • sender(str): The person sending the message
  • recipient(str): The recipient of the message
  • message_body(str): The body of the message
  • priority(int or None): The priority of the message, can be a number 1-5
• return(int): the message id
• raises
  • ValueError: if the message_body exceeds 160 characters
  • TypeError: if the message_body is not a basestring

Use this function like this:

send_message('alice','bob','quantum_secret', 1);

Option 4 - Render in markdown, make collapsible and linkeable

Have the method out of the details block so anchor can be created by markdown engine.

send_message(sender, recipient, message_body, [priority=1])

Send a message to a recipient

• parameters
  • sender(str): The person sending the message
  • recipient(str): The recipient of the message
  • message_body(str): The body of the message
  • priority(int or None): The priority of the message, can be a number 1-5
• return(int): the message id
• raises
  • ValueError: if the message_body exceeds 160 characters
  • TypeError: if the message_body is not a basestring

Use this function like this:

send_message('alice','bob','quantum_secret', 1);

Option 5 - Render in markdown, keep headers simple

Keep headers simple. Header can now be referenced like [this](#send-a-message): this.

Send a message

send_message(sender, recipient, message_body, [priority=1])

• parameters
  • sender(str): The person sending the message
  • recipient(str): The recipient of the message
  • message_body(str): The body of the message
  • priority(int or None): The priority of the message, can be a number 1-5
• return(int): the message id
• raises
  • ValueError: if the message_body exceeds 160 characters
  • TypeError: if the message_body is not a basestring

Send a message to a recipient. This function has undefined behaviour when sender is equal to recipient. The message body should be of this and that format. The priority value will be a figure that is used in the network to probabilistically prioritize high priority messages. Blah blah blah. Blah.

Use this function like this:

send_message('alice','bob','quantum_secret', 1);

Option 6 - Render in markdown, beautify

Beautify a bit (considering we will copy-paste this, it might be less work than we think).

Send a message

send_message(sender, recipient, message_body, [priority=1])

• parameters
  • sender(str): The person sending the message
  • recipient(str): The recipient of the message
  • message_body(str): The body of the message
  • priority(int or None): The priority of the message, can be a number 1-5
• return(int): the message id
• raises
  • ValueError: if the message_body exceeds 160 characters
  • TypeError: if the message_body is not a basestring

🗨️ Send a message to a recipient. This function has undefined behaviour when sender is equal to recipient. The message body should be of this and that format. The priority value will be a figure that is used in the network to probabilistically prioritize high priority messages. Blah blah blah. Blah.

🖊️ Use this function like this:

send_message('alice','bob','quantum_secret', 1);