big documentation pass

bin/_ttbp.py

@@ -1,5 +1,32 @@
 #!/usr/bin/python
 
+'''
+ttbp: tilde town blogging platform
+(also known as the feels engine)
+a console-based blogging program developed for tilde.town
+copyright (c) 2016 ~endorphant (endorphant@tilde.town)
+
+_ttbp.py:
+the beta version of the main console interface
+
+GNU GPL BOILERPLATE:
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+the complete codebase is available at:
+https://github.com/modgethanc/ttbp
+'''
+
 import os
 import random
 import tempfile

bin/chatter.py

@@ -1,5 +1,34 @@
 #!/usr/bin/python
 
+'''
+ttbp: tilde town blogging platform
+(also known as the feels engine)
+a console-based blogging program developed for tilde.town
+copyright (c) 2016 ~endorphant (endorphant@tilde.town)
+
+chatter.py:
+some text processing utilities
+
+GNU GPL BOILERPLATE:
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+the complete codebase is available at:
+https://github.com/modgethanc/ttbp
+'''
+
+import os
+
 import random
 import json
 import os

bin/core.py

@@ -1,5 +1,33 @@
 #!/usr/bin/python
 
+'''
+ttbp: tilde town blogging platform
+(also known as the feels engine)
+a console-based blogging program developed for tilde.town
+copyright (c) 2016 ~endorphant (endorphant@tilde.town)
+
+core.py:
+this is a core handler for some ttbp standalone/output functions
+
+GNU GPL BOILERPLATE:
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+the complete codebase is available at:
+https://github.com/modgethanc/ttbp
+'''
+
 import os
 import time
 import subprocess
@@ -25,6 +53,10 @@ FOOTER = ""
 FILES = []
 
 def load():
+    '''
+    get all them globals set up!!
+    '''
+
     global HEADER
     global FOOTER
 
@@ -34,6 +66,13 @@ def load():
     load_files()
 
 def load_files():
+    '''
+    file loader
+
+    * reads user's nopub file
+    * loads all valid filenames that are not excluded in nopub to global files list
+    '''
+
     global FILES
 
     exclude = []
@@ -54,6 +93,14 @@ def load_files():
     FILES.reverse()
 
 def write(outurl="default.html"):
+    '''
+    main page renderer
+
+    * takes everything currently in FILES and writes a single non-paginated html
+    file
+    * calls write_page() on each file to make permalinks
+    '''
+
     outfile = open(os.path.join(WWW, outurl), "w")
 
     outfile.write("<!--generated by the tilde.town blogging platform on "+time.strftime("%d %B %y")+"\nhttp://tilde.town/~endorphant/ttbp/-->\n\n")
@@ -78,7 +125,12 @@ def write(outurl="default.html"):
     return os.path.join(LIVE+USER,os.path.basename(os.path.realpath(WWW)),outurl)
 
 def write_page(filename):
-    # makes a single permalink page
+    '''
+    permalink generator
+
+    * makes a page out of a single entry for permalinking, using filename/date as
+    url
+    '''
 
     outurl = os.path.join(WWW, "".join(parse_date(filename))+".html")
     outfile = open(outurl, "w")
@@ -103,7 +155,12 @@ def write_page(filename):
     return outurl
 
 def write_entry(filename):
-    # dump given file into entry format, return as list of strings
+    '''
+    entry text generator
+
+    * dump given file into entry format by parsing file as markdown
+    * return as list of strings
+    '''
 
     date = parse_date(filename)
 
@@ -135,8 +192,15 @@ def write_entry(filename):
     return entry
 
 def parse_date(file):
-    # assuming a filename of YYYYMMDD.txt, returns a list of
+    '''
-    # ['YYYY', 'MM', 'DD']
+    parses date out of pre-validated filename
+
+    * assumes a filename of YYYYMMDD.txt
+    * returns a list:
+      [0] 'YYYY'
+      [1] 'MM'
+      [2] 'DD'
+    '''
 
     rawdate = os.path.splitext(os.path.basename(file))[0]
 
@@ -145,14 +209,19 @@ def parse_date(file):
     return date
 
 def meta(entries = FILES):
-    # takes a list of filenames and returns:
+    '''
-    # [0] absolute path
+    metadata generator
-    # [1] ctime
+
-    # [2] wc -w
+    * takes a list of filenames and returns a 2d list:
-    # [3] timestamp "DD month YYYY at HH:MM"
+      [0] absolute path
-    # [4] entry date YYYY-MM-DD
+      [1] ctime
-    # [5] author
+      [2] wc -w
-    # sorted in reverse date order by [4]
+      [3] timestamp "DD month YYYY at HH:MM"
+      [4] entry date YYYY-MM-DD
+      [5] author
+
+    * sorted in reverse date order by [4]
+    '''
 
     meta = []
 
@@ -172,7 +241,11 @@ def meta(entries = FILES):
     return meta
 
 def valid(filename):
-    # check if the filename is YYYYMMDD.txt
+    '''
+    filename validator
+
+    * check if the filename is YYYYMMDD.txt
+    '''
 
     filesplit = os.path.splitext(os.path.basename(filename))
 
@@ -187,8 +260,13 @@ def valid(filename):
     return True
 
 def write_global_feed(blogList):
-    # takes an array of the current global blog status and prints it to
+    '''
-    # set www
+    main ttbp index printer
+
+    * sources README.md for documentation
+    * takes incoming list of formatted blog links for all publishing blogs and
+      prints to blog feed
+    '''
 
     outfile = open(FEED, "w")
 
@@ -241,32 +319,6 @@ def write_global_feed(blogList):
 
     outfile.close()
 
-def make_docs():
-
-    outfile = open(DOCS, "w")
-
-    outfile.write("""\
-<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 3.2//EN\">
-<html>
-    <head>
-        <title>tilde.town feels engine</title>
-        <link rel=\"stylesheet\" href=\"style.css\" />
-    </head>
-    <body>
-        <h1>tilde.town feels engine</h1>
-
-        <h2><a href="https://github.com/modgethanc/ttbp">github
-        repo</a> | <a
-        href="http://tilde.town/~endorphant/blog/20160510.html">state
-        of the ttbp</a></h2> <div class="box">""")
-
-    outfile.write(mistune.markdown(open(os.path.join(SOURCE, "..", "README.md"), "r").read()))
-    outfile.write("""
-    </div>
-  </body>
-</html>
-""")
-    outfile.close()
 #############
 #############
 #############

bin/ttbp.py

@@ -1,5 +1,33 @@
 #!/usr/bin/python
 
+'''
+ttbp: tilde town blogging platform
+(also known as the feels engine)
+a console-based blogging program developed for tilde.town
+copyright (c) 2016 ~endorphant (endorphant@tilde.town)
+
+ttbp.py:
+the main console interface
+
+GNU GPL BOILERPLATE:
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+the complete codebase is available at:
+https://github.com/modgethanc/ttbp
+'''
+
+import os
 import os
 import random
 import tempfile

bin/util.py

@@ -1,5 +1,24 @@
 #!/usr/bin/python
 
+'''
+util.py: frequently used terminal and text processing utilities
+copyright (c) 2016 ~endorphant (endorphant@tilde.town)
+
+GNU GPL BOILERPLATE:
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+'''
+
 import inflect
 import time
 import random

lib/lang.json

@@ -7,12 +7,14 @@
     "good afternoon",
     "good day",
     "good evening",
-    "welcome back"
+    "welcome back",
+    "nice to see you"
       ],
   "bye":[
     "see you later, space cowboy",
     "bye, townie",
-    "until next time, friend"
+    "until next time, friend",
+    "come back whenever"
       ],
   "friend":[
     "friend",