1. How to write docstrings for Ladybug Tools

Overview

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the doc special attribute of that object and may be extracted by software tools (Sphinx is used in ladybug tools) to generate a documentation of a library. In addition to good practice guidelines these software tools require specific conventions to process the docstrings properly, so following them will get you the best results.

Basic docstring guidelines:

• For consistency, always use """triple double quotes""" around docstrings even though the string fits on one line. This makes it easy to later expand it.
• The entire docstring is indented the same as the quotes at its first line with exception of sections.
• Docstrings may include specific sections at class and function levels. Each section begins with a heading line, which ends with a colon. All sections other than the heading should maintain a hanging indent of four spaces. Many of the sections guidelines are extracted from the reStructuredText (reST) markup language. More information can be found here.

Below are detailed explanations of docstrings at each level of a document with examples that illustrate their specific guidelines and their Html documentation output generated by Sphinx.

1.1 Modules

1.2 Functions and Methods

1.3 Classes

1.4 Other Formatting Markups