diff --git a/irrelevant/notebook_generator.py b/irrelevant/notebook_generator.py index d275530..50e86d2 100644 --- a/irrelevant/notebook_generator.py +++ b/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": {}, diff --git a/wtfpython-pypi/wtf_python/main.py b/wtfpython-pypi/wtf_python/main.py index bf76815..0c41d0c 100644 --- a/wtfpython-pypi/wtf_python/main.py +++ b/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)