[nvda-addons] commit/addonTemplate: norrumar: Support for markdown documentation files.
- From: commits-noreply@xxxxxxxxxxxxx
- To: nvda-addons@xxxxxxxxxxxxx
- Date: Sat, 22 Jun 2013 06:27:47 -0000
1 new commit in addonTemplate:
https://bitbucket.org/nvdaaddonteam/addontemplate/commits/363ee49ec13f/
Changeset: 363ee49ec13f
Branch: addonDocSupport
User: norrumar
Date: 2013-06-22 08:26:14
Summary: Support for markdown documentation files.
Affected #: 3 files
diff --git a/.gitignore b/.gitignore
index 3a59e11..6d124be 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,7 @@
+addon/doc/*.css
+addon/doc/en/
+*_docHandler.py
+*.html
*.ini
*.mo
*.pot
diff --git a/README.md b/README.md
index abfc62b..237f27b 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ This template provides the following features you can use to
help NVDA add-on de
* Automatic add-on package creation, with naming and version loaded from a
centralized build variables file (buildVars.py).
* Manifest file creation using a template (manifest.ini.tpl). Build variables
are replaced on this template.
* Compilation of gettext mo files before distribution, when needed.
-- To generate a gettext pot file, please run scons pot. a <adon-name>.pot file
will be created with all gettext messages for your add-on. You need to check
the buildVars.i18nSources variable to comply with your requirements.
+- To generate a gettext pot file, please run scons pot. a **addon-name.pot**
file will be created with all gettext messages for your add-on. You need to
check the buildVars.i18nSources variable to comply with your requirements.
* Automatic generation of manifest localization files directly from gettext po
files. Please make sure buildVar.py is included in i18nFiles.
## Requirements
@@ -23,18 +23,28 @@ You need the following software to use this code for your
NVDA add-ons developme
- a Python distribution (2.7 or greater is recommended). Check the [Python
Website](http://www.python.org) for Windows Installers.
- Scons - [Website](http://www.scons.org/) - version 2.1.0 or greater. Install
it using **easy_install** or grab an windows installer from the website.
- GNU Gettext tools, if you want to have localization support on your add-on -
Recommended. Any Linux distro or cygwin have those installed. You can find
windows builds [here](http://gnuwin32.sourceforge.net/downlinks/gettext.php).
+- Markdown-2.0.1 or greater, if you want to convert documentation files to
HTML documents. You can [Download Markdown-2.0.1 installer for
Windows](https://pypi.python.org/pypi/Markdown/2.0.1).
+
## Usage
-To create a new NVDA add-on, taking advantage of this template:
+### To create a new NVDA add-on, taking advantage of this template: ###
- Create an empty folder to hold the files for your add-on.
-- Copy the **addon** folder, the **buildVars.py** file, the manifest.ini.tpl
file, the manifest-translated.ini.tpl, **SCONSTRUCT**, .gitignore,
.gitattributes and **docHandler.py** files to the created folder.
+- Copy the **addon** folder, the **buildVars.py** file, the manifest.ini.tpl
file, the manifest-translated.ini.tpl, **SCONSTRUCT**, .gitignore and
.gitattributes files to the created folder.
- In the **buildVars.py** file, change variable **addon_info** with your
add-on's information (name, summary, description, version, author and url).
- Put your code in the usual folders for NVDA extension, under the **addon**
folder. For instance: globalPlugins, synthDrivers, etc. You can delete folders
you don't need for your particular add-on package.
- Gettext translations must be placed into
addon\locale\<lang>/LC_MESSAGES\nvda.po.
-- Documentation files must be placed into addon\doc\<lang>/fileName,
readme.html by default. Don't use **docHandler.py** or
**yourAddonName_docHandler.py** as file names contained in **globalPlugins** if
your addon include documentation files; they will be removed to create a menu
item for opening your doc addon, under NVDA's help menu.
-- To package the add-on for distribution, open a command line, change to the
folder that has the **SCONSTRUCT** file and run the **scons** command. The
created add-on, if there were no errors, is placed in the current directory.
+
+### To manage documentation files for your addon: ###
+
+- Copy the **readme.md** and **docHandler.py** files (contained into
addonTemplate) to the first created folder, where you copied **buildVars.py**.
You can also copy **style.css** to improve the presentation of HTML documents.
+- Documentation files (named **readme.mdown**) must be placed into
addon\doc\<lang>/.
+- Don't use **yourAddonName_docHandler.py** as a name for any file contained
in **globalPlugins**; it will be removed to create a menu item for opening your
doc addon, under NVDA's help menu.
+
+### To package the add-on for distribution: ###
+
+- Open a command line, change to the folder that has the **SCONSTRUCT** file
and run the **scons** command. The created add-on, if there were no errors, is
placed in the current directory.
- You can further customize variables in the **buildVars.py** file.
Note that this template only provides a basic add-on structure and build
infrastructure. You may need to adapt it for your specific needs.
diff --git a/sconstruct b/sconstruct
index e6a7a4a..c09af93 100644
--- a/sconstruct
+++ b/sconstruct
@@ -9,12 +9,51 @@ import shutil
import os
import os.path
import zipfile
+import markdown
import configobj
import buildVars
-env = Environment(ENV=os.environ)
+def md2html(source, dest):
+ lang = os.path.basename(os.path.dirname(source)).replace('_', '-')
+ title="{addonSummary}
{addonVersion}".format(addonSummary=buildVars.addon_info["addon-summary"],
addonVersion=buildVars.addon_info["addon-version"])
+ headerDic = {
+ "[[!meta title=\"": "# ",
+ "\"]]": " #",
+ }
+ with codecs.open(source, "r", "utf-8") as f:
+ mdText = f.read()
+ for k, v in headerDic.iteritems():
+ mdText = mdText.replace(k, v, 1)
+ htmlText = markdown.markdown(mdText)
+ with codecs.open(dest, "w", "utf-8") as f:
+ f.write("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n" +
+ "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0
Strict//EN\"\n" +
+ "
\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\";>\n" +
+ "<html xmlns=\"http://www.w3.org/1999/xhtml\";
xml:lang=\"%s\" lang=\"%s\">\n" % (lang, lang) +
+ "<head>\n" +
+ "<meta http-equiv=\"Content-Type\" content=\"text/html;
charset=UTF-8\"/>\n" +
+ "<link rel=\"stylesheet\" type=\"text/css\"
href=\"../style.css\" media=\"screen\"/>\n" +
+ "<title>%s</title>\n" % title +
+ "</head>\n<body>\n"
+ )
+ f.write(htmlText)
+ f.write("\n</body>\n</html>")
+
+def mdownTool(env):
+ mdAction=env.Action(
+ lambda target,source,env: md2html(source[0].path,
target[0].path),
+ lambda target,source,env: 'Generating %s'%target[0],
+ )
+ mdBuilder=env.Builder(
+ action=mdAction,
+ suffix='.html',
+ src_suffix='.mdown',
+ )
+ env['BUILDERS']['markdown']=mdBuilder
+
+env = Environment(ENV=os.environ, tools=[mdownTool])
addonFile =
env.File("{addon-name}-{addon-version}.nvda-addon".format(**buildVars.addon_info))
@@ -59,26 +98,25 @@ env['BUILDERS']['gettextMergePotFile']=env.Builder(
suffix=".pot")
def createAddonHelp(dir):
- docdir = os.path.join(dir, "doc", "en")
- if not os.path.isdir(docdir):
+ if not os.path.isfile("readme.md") or not
os.path.isfile("docHandler.py"):
return
- docFilename =
"{addonName}_docHandler.py".format(addonName=buildVars.addon_info["addon-name"])
+ docdirs = [os.path.join(dir, "doc"), os.path.join(dir, "doc", "en")]
+ for docdir in docdirs:
+ if not os.path.isdir(docdir):
+ os.makedirs(docdir)
+ if os.path.isfile("style.css"):
+ shutil.copy("style.css", docdirs[0])
+ shutil.copyfile("readme.md", os.path.join(docdir, "readme.mdown"))
plugindir = os.path.join(dir, "globalPlugins")
+ docFilename =
"{addonName}_docHandler.py".format(addonName=buildVars.addon_info["addon-name"])
docPath = os.path.join(plugindir, docFilename)
if not os.path.isdir(plugindir):
os.makedirs(plugindir)
- shutil.copy("docHandler.py", plugindir)
- curdir = os.getcwd()
- if os.path.isfile(docPath):
- os.unlink(docPath)
- os.chdir(plugindir)
- os.rename("docHandler.py", docFilename)
- os.chdir(curdir)
+ shutil.copyfile("docHandler.py", docPath)
def createAddonBundleFromPath(path, dest):
""" Creates a bundle from a directory that contains an addon manifest
file."""
basedir = os.path.abspath(path)
- createAddonHelp(basedir)
with zipfile.ZipFile(dest, 'w', zipfile.ZIP_DEFLATED) as z:
# FIXME: the include/exclude feature may or may not be useful.
Also python files can be pre-compiled.
for dir, dirnames, filenames in os.walk(basedir):
@@ -126,6 +164,12 @@ pythonFiles = expandGlobs(buildVars.pythonSources)
for file in pythonFiles:
env.Depends(addon, file)
+#Convert markdown files to html
+createAddonHelp("addon") # We need at least doc in English and should append
an item to Help menu
+for mdownFile in env.Glob(os.path.join('addon', 'doc', '*', '*.mdown')):
+ htmlFile = env.markdown(mdownFile)
+ env.Depends(addon, htmlFile)
+
# Pot target
i18nFiles = expandGlobs(buildVars.i18nSources)
pot = env.gettextPotFile("%s.pot" %
"{addon-name}".format(**buildVars.addon_info), i18nFiles)
Repository URL: https://bitbucket.org/nvdaaddonteam/addontemplate/
--
This is a commit notification from bitbucket.org. You are receiving
this because you have the service enabled, addressing the recipient of
this email.
----------------------------------------------------------------
NVDA add-ons Central: A list for discussing NVDA add-ons
To post a message, send an email to nvda-addons@xxxxxxxxxxxxx.
To unsubscribe, send an email with the subject line of "unsubscribe" (without
quotes) to nvda-addons-request@xxxxxxxxxxxxx.
If you have questions for list moderators, please send a message to
nvda-addons-moderators@xxxxxxxxxxxxx.
Community addons can be found here: http://addons.nvda-project.org
Other related posts:
- » [nvda-addons] commit/addonTemplate: norrumar: Support for markdown documentation files. - commits-noreply
