The new documentation system has been finished. Doc needs to be updated

MCV-Software · Nov 7, 2014 · 9e79bdf · 9e79bdf
1 parent 76a2b0b
commit 9e79bdf
Show file tree

Hide file tree

Showing 39 changed files with 20,386 additions and 3 deletions.
diff --git a/doc/__init__.py b/doc/__init__.py
diff --git a/doc/documentation_importer.py b/doc/documentation_importer.py
@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+""" This script converts the hold documentation (saved in markdown files) in a python file with a list of strings to translate it using gettext."""
+
+def prepare_documentation_in_file(fileSource, fileDest):
+	""" This takes documentation written in a markdown file and put all the contents in a python file, to create a internationalized documentation.
+	 @fileSource str: A markdown(.md) file.
+	 @fileDest str: A file where this will put the new strings"""
+
+	f1 = open(fileSource, "r")
+	f2 = open(fileDest, "w")
+	lns = f1.readlines()
+	f2.write("# -*- coding: utf-8 -*-\n")
+	f2.write("documentation = []\n")
+	for i in lns:
+		if len(i) > 2:
+			newvar = "documentation.append(_(u\"\"\"%s\"\"\"))\n" % (i[:-2])
+		else:
+			newvar = "documentation.append(_(u\"\"\"%s\"\"\"))\n" % (i)
+		f2.write(newvar)
+	f1.close()
+	f2.close()
+
+
diff --git a/doc/generator.py b/doc/generator.py
@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+import markdown
+import os
+from codecs import open as _open
+import languageHandler
+languageHandler.setLanguage("en")
+import strings
+
+# the list of supported language codes of TW Blue
+languages = ["en", "es", "fr", "gl"]
+#"eu", "ar", "ca", "es", "fi", "fr", "gl", "hu", "it", "pl", "pt", "ru", "tr"]
+
+def generate_document(language):
+ reload(languageHandler)
+ languageHandler.setLanguage(language)
+ reload(strings)
+ markdown_file = markdown.markdown("\n".join(strings.documentation[1:]), extensions=["markdown.extensions.toc"])
+ first_html_block = """<!doctype html>
+ <html lang="%s">
+ <head>
+  <title>%s</title>
+  <meta charset="utf-8">
+  </head>
+  <body>
+  <header><h1>%s</h1></header>
+  """ %  (language, strings.documentation[0], strings.documentation[0])
+ first_html_block = first_html_block+ markdown_file
+ first_html_block = first_html_block + "\n</body>\n</html>"
+ if not os.path.exists(language):
+  os.mkdir(language)
+ mdfile = _open("%s/manual.html" % language, "w", encoding="utf-8")
+ mdfile.write(first_html_block)
+ mdfile.close()
+
+def create_documentation():
+ print("Creating documentation in the supported languages...\n")
+ for i in languages:
+  print("Creating documentation for: %s" % (i,))
+  generate_document(i)
+ print("Done")
+
+create_documentation()
diff --git a/doc/languageHandler.py b/doc/languageHandler.py
@@ -0,0 +1,176 @@
+import __builtin__
+import os
+import sys
+import ctypes
+import locale
+import gettext
+#import paths
+import platform
+
+# A fix for the mac locales
+if platform.system() != 'Windows':
+ if locale.getlocale()[0] is None:
+  locale.setlocale(locale.LC_ALL, 'en_US')
+
+#a few Windows locale constants
+LOCALE_SLANGUAGE=0x2
+LOCALE_SLANGDISPLAYNAME=0x6f
+
+curLang="en"
+
+def localeNameToWindowsLCID(localeName):
+	"""Retreave the Windows locale identifier (LCID) for the given locale name
+	@param localeName: a string of 2letterLanguage_2letterCountry or or just 2letterLanguage
+	@type localeName: string
+	@returns: a Windows LCID
+	@rtype: integer
+	""" 
+	#Windows Vista is able to convert locale names to LCIDs
+	func_LocaleNameToLCID=getattr(ctypes.windll.kernel32,'LocaleNameToLCID',None)
+	if func_LocaleNameToLCID is not None:
+		localeName=localeName.replace('_','-')
+		LCID=func_LocaleNameToLCID(unicode(localeName),0)
+	else: #Windows doesn't have this functionality, manually search Python's windows_locale dictionary for the LCID
+		localeName=locale.normalize(localeName)
+		if '.' in localeName:
+			localeName=localeName.split('.')[0]
+		LCList=[x[0] for x in locale.windows_locale.iteritems() if x[1]==localeName]
+		if len(LCList)>0:
+			LCID=LCList[0]
+		else:
+			LCID=0
+	return LCID
+
+def getLanguageDescription(language):
+	"""Finds out the description (localized full name) of a given local name"""
+	desc=None
+	if platform.system() == "Windows":
+		LCID=localeNameToWindowsLCID(language)
+		if LCID!=0:
+			buf=ctypes.create_unicode_buffer(1024)
+			if '_' not in language:
+				res=ctypes.windll.kernel32.GetLocaleInfoW(LCID,LOCALE_SLANGDISPLAYNAME,buf,1024)
+			else:
+				res=0
+			if res==0:
+				res=ctypes.windll.kernel32.GetLocaleInfoW(LCID,LOCALE_SLANGUAGE,buf,1024)
+			desc=buf.value
+	elif platform.system() == "Linux" or not desc:
+		desc={
+			"am":pgettext("languageName","Amharic"),
+			"an":pgettext("languageName","Aragonese"),
+			"es":pgettext("languageName","Spanish"),
+			"pt":pgettext("languageName","Portuguese"),
+			"ru":pgettext("languageName","Russian"),
+			"it":pgettext("languageName","italian"),
+			"tr":pgettext("languageName","Turkey"),
+			"gl":pgettext("languageName","Galician"),
+			"ca":pgettext("languageName","Catala"),
+			"eu":pgettext("languageName","Vasque"),
+			"pl":pgettext("languageName","polish"),
+			"ar":pgettext("languageName","Arabic"),
+			"ne":pgettext("languageName","Nepali"),
+			"sr":pgettext("languageName","Serbian (Latin)"),
+		}.get(language,None)
+	return desc
+
+def getAvailableLanguages():
+	"""generates a list of locale names, plus their full localized language and country names.
+	@rtype: list of tuples
+	"""
+	#Make a list of all the locales found in NVDA's locale dir
+	l=[x for x in os.listdir("locales") if not x.startswith('.')]
+	l=[x for x in l if os.path.isfile('locales/%s/LC_MESSAGES/twblue-documentation.mo' % x)]
+	#Make sure that en (english) is in the list as it may not have any locale files, but is default
+	if 'en' not in l:
+		l.append('en')
+		l.sort()
+	#For each locale, ask Windows for its human readable display name
+	d=[]
+	for i in l:
+		desc=getLanguageDescription(i)
+		label="%s, %s"%(desc,i) if desc else i
+		d.append(label)
+	#include a 'user default, windows' language, which just represents the default language for this user account
+	l.append("system")
+	# Translators: the label for the Windows default NVDA interface language.
+	d.append(_("User default"))
+	#return a zipped up version of both the lists (a list with tuples of locale,label)
+	return zip(l,d)
+
+def makePgettext(translations):
+	"""Obtaina  pgettext function for use with a gettext translations instance.
+	pgettext is used to support message contexts,
+	but Python 2.7's gettext module doesn't support this,
+	so NVDA must provide its own implementation.
+	"""
+	if isinstance(translations, gettext.GNUTranslations):
+		def pgettext(context, message):
+			message = unicode(message)
+			try:
+				# Look up the message with its context.
+				return translations._catalog[u"%s\x04%s" % (context, message)]
+			except KeyError:
+				return message
+	else:
+		def pgettext(context, message):
+			return unicode(message)
+	return pgettext
+
+def setLanguage(lang):
+	system = platform.system()
+	global curLang
+	try:
+		if lang=="system":
+			if system == "Windows":
+				windowsLCID=ctypes.windll.kernel32.GetUserDefaultUILanguage()
+				localeName=locale.windows_locale[windowsLCID]
+			else:
+				localeName=locale.getlocale()[0]
+			trans=gettext.translation('twblue-documentation', localedir="locales", languages=[localeName])
+			curLang=localeName
+		else:
+			trans=gettext.translation("twblue-documentation", localedir="locales", languages=[lang])
+			curLang=lang
+			localeChanged=False
+			#Try setting Python's locale to lang
+			try:
+				locale.setlocale(locale.LC_ALL, lang)
+				localeChanged=True
+			except:
+				pass
+			if not localeChanged and '_' in lang:
+				#Python couldn'tsupport the language_country locale, just try language.
+				try:
+					locale.setlocale(locale.LC_ALL, lang.split('_')[0])
+				except:
+					pass
+			#Set the windows locale for this thread (NVDA core) to this locale.
+			if system == "Windows":
+				LCID=localeNameToWindowsLCID(lang)
+				ctypes.windll.kernel32.SetThreadLocale(LCID)
+	except IOError:
+		trans=gettext.translation("twblue-documentation",fallback=True)
+		curLang="en"
+	trans.install(unicode=True)
+	# Install our pgettext function.
+	__builtin__.__dict__["pgettext"] = makePgettext(trans)
+
+def getLanguage():
+	return curLang
+
+def normalizeLanguage(lang):
+	"""
+	Normalizes a  language-dialect string  in to a standard form we can deal with.
+	Converts  any dash to underline, and makes sure that language is lowercase and dialect is upercase.
+	"""
+	lang=lang.replace('-','_')
+	ld=lang.split('_')
+	ld[0]=ld[0].lower()
+	#Filter out meta languages such as x-western
+	if ld[0]=='x':
+		return None
+	if len(ld)>=2:
+		ld[1]=ld[1].upper()
+	return "_".join(ld)
+
diff --git a/doc/locales/ar/lc_messages/twblue-documentation.mo b/doc/locales/ar/lc_messages/twblue-documentation.mo