Pharaoh: Cleaned up Documentation

Signed-off-by: Sam Kleinman <[email protected]>

pharaoh/pharaoh/app/static/javascript/scripts.js

@@ -1,3 +1,19 @@
+/**
+ * Copyright 2014 MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+**/
+
 $(document).ready(function(){
     $(".edit").on('click',edit);
     $(".approve").on('click',approve);

pharaoh/pharaoh/app/views.py

@@ -131,20 +131,28 @@ def unapprove_translation():
 
 @app.route('/edit/<username>/<language>/<path:file>/423')
 def lock_error(username, language, file):
+    ''' This function is called when a user tries to do something in a file
+    but doesn't have a lock and thu can't
+    '''
     return render_template("423.html",
                            username=username,
                            language=language,
                            file=file)
 
 @app.route('/download-all/<language>/<path:file>')
 def download_single_po(language, file):
+    ''' This function downloads all translations from a single po file
+    '''
     po = generate_fresh_po_text(file, 'en', language, db, True)
     response = make_response(po)
     response.headers["Content-Disposition"] = "attachment; filename={0}.po".format(file)
     return response
 
 @app.route('/download-approved/<language>/<path:file>')
 def download_single_po_approved(language, file):
+    ''' This function downloads all approved translations from a single
+    po file
+    '''
     po = generate_fresh_po_text(file, 'en', language, db, False)
     response = make_response(po)
     response.headers["Content-Disposition"] = "attachment; filename={0}.po".format(file)
@@ -153,6 +161,9 @@ def download_single_po_approved(language, file):
 @app.route('/download-all/<language>/')
 @app.route('/download-all/<language>')
 def download_all_po(language):
+    ''' This function downloads all translations from all 
+    po files
+    '''
     po = generate_all_po_files( 'en', language, db, True)
     response = make_response(po)
     response.headers["Content-Disposition"] = "attachment; filename={0}.tar.gz".format(language)
@@ -161,18 +172,23 @@ def download_all_po(language):
 @app.route('/download-approved/<language>/')
 @app.route('/download-approved/<language>')
 def download_all_po_approved(language):
+    ''' This function downloads all approved translations from all 
+    po files
+    '''
     po = generate_all_po_files( 'en', language, db, False)
     response = make_response(po)
     response.headers["Content-Disposition"] = "attachment; filename={0}.tar.gz".format(language)
     return response
 
 @app.route('/admin', methods=['GET'])
 def admin():
+    ''' This function produces an admin page'''
     files = models.get_file_paths()
     return render_template("admin.html", file_list=files)
 
 @app.route('/upload', methods=['POST'])
 def upload():
+    ''' This function uploads the given tar ball to mongodb'''
     app.logger.info(request.files['file'])
     app.logger.info(request.form)
     put_po_data_in_mongo(request.files['file'], 

pharaoh/pharaoh/mongo_to_po.py

@@ -38,6 +38,8 @@
 def write_po_file(po_fn, source_language, target_language, db, is_all):
     ''' writes approved or all trnalstions to file
     :param string po_fn: the path to the current po file to write
+    :param string source_language: language to translate from 
+    :param string target_language: language to translate to 
     :param database db: mongodb database
     :param boolean is_all: whether or not you want all or just approved translations
     '''
@@ -65,6 +67,8 @@ def write_po_file(po_fn, source_language, target_language, db, is_all):
 def write_mongo_to_po_files(path, source_language, target_language, db_host, db_port, db_name, is_all):
     ''' goes through directory tree and writes po files to mongo
     :param string path: the path to the top level directory of the po_files
+    :param string source_language: language to translate from 
+    :param string target_language: language to translate to 
     :param string db_host: the hostname of the database
     :param int db_port: the port of the database
     :param string db_name: the name of the database
@@ -84,6 +88,13 @@ def write_mongo_to_po_files(path, source_language, target_language, db_host, db_
         write_po_file(fn, source_language, target_language, db, is_all)
 
 def generate_fresh_po_text(po_fn, source_language, target_language, db, is_all):
+    ''' goes through all of the sentences in a po file in the database and writes them out to a fresh po file
+    :param string po fn: the path to a given po file as it would be found in the database
+    :param string source_language: language to translate from 
+    :param string target_language: language to translate to 
+    :param database db: the instance of the database
+    :param boolean is_all: whether or not you want all or just approved translations
+    '''
     po = polib.POFile()
     po.metadata = {
         u'Project-Id-Version': 'uMongoDB Manual',
@@ -116,13 +127,21 @@ def generate_fresh_po_text(po_fn, source_language, target_language, db, is_all):
         entry = polib.POEntry(
             msgid=unicode(sentence['source_sentence'].strip()),
             msgstr=unicode(translation),
-            #comment=unicode(sentence['source_location'].strip()),
+            comment=unicode(sentence['source_location'].strip()),
             tcomment=unicode(sentence['sentenceID'].strip())
             )
         po.append(entry)
     return getattr(po, '__unicode__')()
 
 def generate_all_po_files(source_language, target_language, db, is_all):
+    ''' goes through all of the files in the database for a pair of langauges and 
+    writes them all out to fresh po files. It then tars them up before returning
+    the value of the tar
+    :param string source_language: language to translate from 
+    :param string target_language: language to translate to 
+    :param database db: the instance of the database
+    :param boolean is_all: whether or not you want all or just approved translations
+    '''
     file_list = db['files'].find({'source_language': source_language,
                                   'target_language': target_language},
                                  {'_id': 1, 'file_path': 1})

pharaoh/pharaoh/po_to_mongo.py

@@ -104,15 +104,15 @@ def put_po_files_in_mongo(path, username, status, source_language, target_langua
 
 
 def put_po_data_in_mongo(po_tar, username, status, source_language, target_language, db):
-    '''go through directories and write the po file to mongo
-    :param string po_fn: the filename for the po file
-    :param string po_data: the po_file data
+    '''go through a tar of directories and write the po file to mongo
+    :param string po_tar: the tar of a set of po files
     :param string username: the username of the translator
     :param string status: the status of the translations
     :param string source_language: The source_language of the translations
     :param string target_language: The target_language of the translations
     :param database db: the mongodb database
     '''
+
     tar = tarfile.open(fileobj=po_tar)
     for member in tar.getmembers():
         if os.path.splitext(member.name)[1] not in ['.po', '.pot']:

pharaoh/pharaoh/serialization.py

@@ -14,6 +14,10 @@
 
 import json
 import yaml
+import logging
+
+logger = logging.getLogger('pharaoh.serialization')
+
 
 def ingest_yaml_list(*filenames):
     o = []

pharaoh/pharaoh/utils.py

@@ -21,6 +21,10 @@
 logger = logging.getLogger('pharaoh.utils')
 
 def load_json(file_name, db):
+    ''' This function loads json into a dictionary
+    :param string file_name: The name of the json file
+    :param database db: The instance of the mongodb database
+    '''
     file_no_ext = os.path.basename(file_name)
     file_no_ext = os.path.splitext(file_no_ext)[0]
     with open(file_name,"r") as file:
@@ -31,6 +35,10 @@ def load_json(file_name, db):
 
 
 def get_file_list(path, input_extension=['po', 'pot']):
+    '''Returns of a list of files with certain extensions in a given directory tree
+    :param string path: The path to the top of directory tree
+    :param list input_extension: list of file extensions (without a dot) that are returned
+    '''
     file_list = []
     if os.path.isfile(path):
         return [path]