add comments

githublog.py

@@ -3,22 +3,35 @@
 """
 File: githublog.py
 
-Hugo assistance to generate a special README file, including all posts title inside
-as a TOC.
+This is a quick&dirty tool helping you generating a TOC file for blog repo based on Hugo.
+
+Usage:
+
+python githublog.py
+
+IMPORTANT
+
+Before starting, you should check that the working-directory is right at the root of
+the hugo blog and managed by git (is preferred)
 
-This will make blog repo to be a blog inplace.
 """
+
 import os
 import string
 import subprocess
 from posixpath import join as urljoin
 
-POSTS_ROOT = 'content'
-EXTS = ['.md', '.rst']
-README = 'README.md'
-GITREPO = 'http://git.wanbits.io/joe/blog'
+POSTS_ROOT = 'content'      # hugo root dir of posts.
+EXTS = ['.md', '.rst']      # post file extensions. (should be in lowercase)
+README = 'README.md'        # filename to be generated.
+GITREPO = 'http://git.wanbits.io/joe/blog'      # repo address of blog code.
+BRANCH = 'master'           # publish branch
+
 
 def get_git_remote():
+    """ Get git remote url  
+        should be executed in git directory and with git installed.
+    """
     proc = subprocess.Popen(['git', 'remote', '-v'], stdout=subprocess.PIPE, shell=True)
     (out, err) = proc.communicate()
     if err:
@@ -33,19 +46,34 @@ def get_git_remote():
     return None if len(values) < 1 else values[0]
 
 
+def get_git_branch():
+    """ Get current git branch """
+    pass
+
+
 def get_category(dir):
-    ''' '''
+    ''' 
+    Get blog category by dir(ectory)
+    '''
     parts = dir.split(os.sep)
     return os.sep.join(parts[1:])
 
+# repo remote
 remote = get_git_remote() if not GITREPO else GITREPO
-
 if not remote:
     print('not a git repo, quit')
     exit(1)
 
-posts = {}
-# find out all non-draft posts
+# current git branch
+branch = get_git_branch() if not BRANCH else BRANCH
+if not branch:
+    print('no branch?')
+    exit(1)
+
+# all posts, searching result 
+# map[str][list]
+posts = {} 
+## find out all non-draft posts
 for r, dl, fl in os.walk(POSTS_ROOT):
     if fl:
         cate = get_category(r)
@@ -57,7 +85,7 @@ for r, dl, fl in os.walk(POSTS_ROOT):
             continue
         fullname = os.path.join(r, f)
         comment_started = False
-        metas = {}
+        metas = {}  # hugo post meta-info map[str]str
         with open(fullname, 'r', encoding='utf-8') as h:
             line = h.readline().strip()
             while line:
@@ -65,27 +93,25 @@ for r, dl, fl in os.walk(POSTS_ROOT):
                     if not comment_started:
                         comment_started = True
                     else:
-                        break
+                        break   # from while
                 else:
                     parts = line.split(': ')
                     if len(parts) != 2:
-                        break
+                        break   # from while
                     metas[parts[0].strip().lower()] = parts[1].strip().lower()
-                    metas['file'] = f
-
                 line = h.readline().strip()
         if metas.get('draft') == 'false':
+            metas['file'] = f
             posts[cate].append(metas)
 
-# generate README.md
+## generate README.md
 with open(README, 'wt', encoding='utf-8') as h:
-    h.write('')
     for k, v in posts.items():
         h.write('## {}\n\n'.format(k))
+        # sortint posts by published date.
         v = sorted(v, key=lambda metas: metas.get('date'), reverse=True)
         for metas in v:
-            h.write('- [{}]({})\n'.format(metas.get('title'), urljoin(remote, 'src/master', POSTS_ROOT, k, metas.get('file'))))
-        
+            h.write('- [{}]({})\n'.format(metas.get('title'), urljoin(remote, 'src', branch, POSTS_ROOT, k, metas.get('file'))))
         h.write('\n')
 
-print('done.')
+print('done.')