Merge pull request #277 from fluencydoc/trelent-documentation

Added docstrings to several undocumented functions

irrelevant/notebook_generator.py

@@ -55,6 +55,12 @@ That being said, most of the examples do work as expected. If you face any troub
 
 
 def generate_code_block(statements, output):
+    """
+    Generates a code block that executes the given statements.
+
+    :param statements: The list of statements to execute.
+    :type statements: list(str)
+    """
     global sequence_num
     result = {
         "type": "code",
@@ -67,6 +73,9 @@ def generate_code_block(statements, output):
 
 
 def generate_markdown_block(lines):
+    """
+    Generates a markdown block from a list of lines.
+    """
     global sequence_num
     result = {
         "type": "markdown",
@@ -85,6 +94,12 @@ def is_interactive_statement(line):
 
 
 def parse_example_parts(lines, title, current_line):
+    """
+    Parse the given lines and return a dictionary with two keys:
+    build_up, which contains all the text before an H4 (explanation) is encountered,
+    and
+    explanation, which contains all the text after build_up until --- or another H3 is encountered.
+    """
     parts = {
         "build_up": [],
         "explanation": []
@@ -191,6 +206,14 @@ def remove_from_beginning(tokens, line):
 
 
 def inspect_and_sanitize_code_lines(lines):
+    """
+    Remove lines from the beginning of a code block that are not statements.
+
+    :param lines: A list of strings, each representing a line in the code block.
+    :returns is_print_present, sanitized_lines: A boolean indicating whether print was present in the original code and a list of strings representing
+    sanitized lines.  The latter may be an empty list if all input lines were removed as comments or whitespace (and thus did not contain any statements).
+    This function does not remove blank lines at the end of `lines`.
+    """
     tokens_to_remove = STATEMENT_PREFIXES
     result = []
     is_print_present = False
@@ -203,6 +226,23 @@ def inspect_and_sanitize_code_lines(lines):
 
 
 def convert_to_cells(cell_contents, read_only):
+    """
+    Converts a list of dictionaries containing markdown and code cells into a Jupyter notebook.
+
+    :param cell_contents: A list of dictionaries, each
+    dictionary representing either a markdown or code cell. Each dictionary should have the following keys: "type", which is either "markdown" or "code",
+    and "value". The value for type = 'markdown' is the content as string, whereas the value for type = 'code' is another dictionary with two keys,
+    statements and output. The statements key contains all lines in between ```py\n``` (including) until ```\n```, while output contains all lines after
+    ```.output py\n```. 
+    :type cell_contents: List[Dict]
+
+        :param read_only (optional): If True then only print outputs are included in converted
+    cells. Default False
+        :type read_only (optional): bool
+
+        :returns A Jupyter notebook containing all cells from input parameter `cell_contents`.
+    Each converted cell has metadata attribute collapsed set to true if it's code-cell otherwise None if it's markdow-cell.
+    """
     cells = []
     for stuff in cell_contents:
         if stuff["type"] == "markdown":
@@ -269,6 +309,9 @@ def convert_to_cells(cell_contents, read_only):
 
 
 def convert_to_notebook(pre_examples_content, parsed_json, post_examples_content):
+    """
+    Convert a JSON file containing the examples to a Jupyter Notebook.
+    """
     result = {
         "cells": [],
         "metadata": {},

wtfpython-pypi/wtf_python/main.py

@@ -13,6 +13,10 @@ file_path = join(dirname(dirname(realpath(__file__))), "content.md")
 
 
 def fetch_updated_doc():
+    """
+    Fetch the latest version of the file at `url` and save it to `file_path`.
+    If anything goes wrong, do nothing.
+    """
     try:
         print("Fetching the latest version...")
         urlretrieve(url, file_path)