From dccb1570d8322fea125d8237b8cc32ccee10ed9b Mon Sep 17 00:00:00 2001 From: endorphant Date: Sat, 21 May 2016 23:36:21 -0400 Subject: [PATCH] more documentation updates holy crap! here i am, about a decade and a half after my first Formal Instruction in programming, and i suddenly understand code documentation. part of this is that sometimes i stare at functions forgetting why they're there, or start writing a function with the distinct feeling that i'm typing code i've already typed before, and realize that maybe there's a better way. so i skimmed code from other people that i've used in my own repos, and lifted the general gist of their commenting style while doing things that feel right to me. i still don't know exactly how i like things, but i'm learning. this is the best way i learn things. then. then! i learned that i can just pydoc any of my modules and pydoc will generate literally the same thing that i read when i pydoc other module! what. WHAT. this is amazing. i feel like a real person. i understand where those docs come from now, and how to make them myself. i'm learning so much. why does this feel so amazing. all of this is in a commit message that i'm going to fire off into the sun but i just need to put this out there because this feels important. --- bin/_ttbp.py | 103 +++++++++++++++++++++++++++++++++++++++++++++----- bin/ttbp.py | 1 - bin/util.py | 32 +++++++++++++++- changelog.txt | 6 ++- 4 files changed, 129 insertions(+), 13 deletions(-) diff --git a/bin/_ttbp.py b/bin/_ttbp.py index 03ab750..7160db9 100644 --- a/bin/_ttbp.py +++ b/bin/_ttbp.py @@ -81,6 +81,12 @@ SUBJECTS = ["help request", "bug report", "feature suggestion", "general comment ## def redraw(leftover=""): + ''' + screen clearing + + * clears the screen and reprints the banner, plus whatever leftover text to be hilights + ''' + os.system("clear") print(BANNER) print(SPACER) @@ -88,9 +94,16 @@ def redraw(leftover=""): print("> "+leftover+"\n") def start(): + ''' + main engine head + + * called on program start + * calls config check + * proceeds to main menu + * handles ^c and ^d ejects + ''' + redraw() - #print(chatter.say("greet")+", "+chatter.say("friend")) - #print("(remember, you can always press ctrl-c to come home)\n") print(""" if you don't want to be here at any point, press and it'll all go away. just keep in mind that you might lose anything you've started here.\ @@ -117,13 +130,29 @@ just keep in mind that you might lose anything you've started here.\ break def stop(): + ''' + closer + + * prints ending text + ''' + return "\n\n\t"+chatter.say("bye")+"\n\n" def check_init(): + ''' + user handler + + * checks for presence of ttbprc + * checks for last run version + ''' + global SETTINGS + print("\n\n") if os.path.exists(os.path.join(os.path.expanduser("~"),".ttbp")): print(chatter.say("greet")+", "+USER+".\n") + + ## ttbprc validation while not os.path.isfile(TTBPRC): setup_handler() try: @@ -135,6 +164,7 @@ def check_init(): if not updated(): print(update_version()) + ## when ready, enter main program and load core engine raw_input("press to explore your feels.\n\n") core.load() @@ -143,32 +173,45 @@ def check_init(): return init() def init(): + ''' + new user creation + + * introduces user + * calls setup functinos + ''' + try: raw_input(""" i don't recognize you, stranger. let's make friends. -press to begin, or to get out of here. +press to begin, or to get out of here.\ """) except KeyboardInterrupt: print("\n\nthanks for checking in! i'll always be here.\n\n") quit() + ## record user in source list users = open(USERFILE, 'a') users.write(USER+"\n") users.close() + + ## make .ttbp directory structure subprocess.call(["mkdir", PATH]) subprocess.call(["mkdir", CONFIG]) subprocess.call(["mkdir", DATA]) + ## create header file header = gen_header() headerfile = open(os.path.join(CONFIG, "header.txt"), 'w') for line in header: headerfile.write(line) headerfile.close() + ## copy footer and default stylesheet subprocess.call(["cp", os.path.join(SOURCE, "config", "defaults", "footer.txt"), CONFIG]) subprocess.call(["cp", os.path.join(SOURCE, "config", "defaults", "style.css"), CONFIG]) + ## run user-interactive setup and load core engine setup() core.load() @@ -176,10 +219,17 @@ press to begin, or to get out of here. return "" def gen_header(): - header =""" + ''' + header generator + + builds header to insert username + ''' + + header ="""\ + ~"""+USER+""" on TTBP @@ -198,6 +248,13 @@ def gen_header(): return header def setup_handler(): + ''' + setup wrapper function + + * calls setup() + * handles ^c + ''' + print("\nyour ttbp configuration doesn't look right. let's make you a fresh copy.\n\n") try: setup() @@ -206,6 +263,17 @@ def setup_handler(): setup() def setup(): + ''' + master setup function + + * editor selection + * publishing toggle + * publish/unpublish as needed + * directory selection + + TODO: break this out better? + ''' + global SETTINGS # editor selection @@ -219,6 +287,7 @@ def setup(): if publishing(): print("publish directory: ~"+USER+"/public_html/"+SETTINGS.get("publish dir")) + # save settings ttbprc = open(TTBPRC, "w") ttbprc.write(json.dumps(SETTINGS, sort_keys=True, indent=2, separators=(',',':'))) @@ -231,6 +300,12 @@ def setup(): ## menus def print_menu(menu): + ''' + pretty menu handler + + * takes list of options and prints them + ''' + i = 0 for x in menu: line = [] @@ -244,6 +319,10 @@ def print_menu(menu): i += 1 def main_menu(): + ''' + main navigation menu + ''' + menuOptions = [ "record your feels", "review your feels", @@ -252,8 +331,8 @@ def main_menu(): "change your settings", "send some feedback", "see credits"] + print("you're at ttbp home. remember, you can always press to come back here.\n\n") - #print("you're at ttbp home.\n\n") print_menu(menuOptions) try: @@ -301,9 +380,14 @@ def main_menu(): return main_menu() -### - def feedback_menu(): + ''' + feedback handling menu + + * selects feedback type + * calls feedback writing function + ''' + print("you're about to send mail to ~endorphant about ttbp\n\n") print_menu(SUBJECTS) @@ -443,7 +527,7 @@ press to begin recording your feels. return -def send_feedback(entered, subject="none", mailbox=os.path.join(FEEDBACK, USER+"-"+time.strftime("%Y%m%d-%H%M")+".msg")): +def send_feedback(entered, subject="none"): message = "" @@ -817,5 +901,6 @@ def update_version(): ##### -start() +if __name__ == '__main__': + start() #print("ttbp beta is out to lunch. bbl.") diff --git a/bin/ttbp.py b/bin/ttbp.py index d3f4278..a90ff3f 100644 --- a/bin/ttbp.py +++ b/bin/ttbp.py @@ -27,7 +27,6 @@ the complete codebase is available at: https://github.com/modgethanc/ttbp ''' -import os import os import random import tempfile diff --git a/bin/util.py b/bin/util.py index 4993877..b94b7d8 100644 --- a/bin/util.py +++ b/bin/util.py @@ -33,6 +33,10 @@ lastcolor = colorama.Fore.RESET p = inflect.engine() def set_rainbow(): + ''' + prints a random terminal color code + ''' + global lastcolor color = lastcolor @@ -44,9 +48,17 @@ def set_rainbow(): print(color) def reset_color(): + ''' + prints terminal color code reset + ''' + print(colorama.Fore.RESET) def attach_rainbow(): + ''' + returns a random terminal color code, presumably to be 'attached' to a string + ''' + global lastcolor color = lastcolor @@ -57,12 +69,28 @@ def attach_rainbow(): return color def attach_reset(): + ''' + returns terminal color code reset, presumably to be 'attached' to a string + ''' + return colorama.Style.RESET_ALL def hilight(text): + ''' + takes a string and highlights it on return + ''' + return colorama.Style.BRIGHT+text+colorama.Style.NORMAL def pretty_time(time): + ''' + human-friendly time formatter + + takes an integer number of seconds and returns a phrase that describes it, + using the largest possible figure, rounded down (ie, time=604 returns '10 + minutes', not '10 minutes, 4 seconds' or '604 seconds') + ''' + m, s = divmod(time, 60) if m > 0: h, m = divmod(m, 60) @@ -86,7 +114,9 @@ def pretty_time(time): return p.no("second", s) def genID(digits=5): - # makes a string of digits + ''' + returns a string-friendly string of digits, which can start with 0 + ''' id = "" x = 0 diff --git a/changelog.txt b/changelog.txt index a2aef62..9aa350a 100644 --- a/changelog.txt +++ b/changelog.txt @@ -17,10 +17,12 @@ TO-DO: (flair) -graffiti wall - -command line flags: - (maybe; not sure i want this to be a feature at all) + -command line flags + *maybe; not sure i want this to be a feature at all -shortcut to most recent feels, writing entry, seeing own entry -#hashtags + -rainbow menu selection + -break out hardcoded globals into config files ------