How to generate source code documentation in TinyOS (nesdoc)

TinyOS uses Nesdoc to generate documentation from source code (as Doxygen does), to build the documents (found later in $TOSROOT/doc folder under your platform name) just type (and replace with your platform's name):

make platform docs

This should go smoothly but... there are small things to tweak, for example:


error: StorageVolumes.h: No such file or directory

If you include the STM25P component (external flash memory support), if fails locating StorageVolumes.h file, as this file is generated in build time from the definitions in your platform's target file (at tos/support/make):


VOLUME_FILE = volumes-stm25p.xml
VOLUME_ALLOCATOR ?= tos-storage-stm25p

One quick work-around is to previously build the application and then copy the generated StorageVolumes.h file from the resulting build/platform location to your application path, then run the make docs command again.

I did found the following errors:


Traceback (most recent call last):
  File "/usr/lib/tinyos/nesdoc/archive.py", line 352, in <module>
    doc.writexml(ifile)
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 1751, in writexml
    node.writexml(writer, indent, addindent, newl)
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 816, in writexml
    node.writexml(writer, indent+addindent, addindent, newl)
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 816, in writexml
    node.writexml(writer, indent+addindent, addindent, newl)
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 816, in writexml
    node.writexml(writer, indent+addindent, addindent, newl)
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 816, in writexml
    node.writexml(writer, indent+addindent, addindent, newl)
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 812, in writexml
    self.childNodes[0].writexml(writer, '', '', '')
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 1040, in writexml
    _write_data(writer, "%s%s%s" % (indent, self.data, newl))
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 297, in _write_data
    writer.write(data)
UnicodeEncodeError: 'ascii' codec can't encode characters in position 244-245: ordinal not in range(128)



Just edit archive.py (see error log for details on its location and change:

--- /usr/lib/tinyos/nesdoc/archive_old.py
+++ /usr/lib/tinyos/nesdoc/archive.py
@@ -1,4 +1,5 @@
 # -*- python -*-
+# -*- coding: utf-8 -*- 
 # Copyright (c) 2005 Intel Corporation
 # All rights reserved.
 #
@@ -43,6 +44,7 @@
 from nesdoc.graph import generate_graph
 from nesdoc.html import *
 import os
+import codecs

 def check(x):
   if not x:
@@ -292,7 +294,7 @@
       refd.appendChild(qnameidx[qname].cloneNode(True))
     doc.appendChild(copy)
-    ifile = file(filename, "w")
-    doc.writexml(ifile)
+    ifile = file(filename, "wb")
+    doc.writexml(codecs.open(filename, 'wb', 'utf-8'), encoding='utf-8')
     doc.unlink()
     ifile.close(

And this one:


Traceback (most recent call last):
  File "/usr/lib/tinyos/nesdoc/genhtml.py", line 96, in <module>
    generate_component(ixml.documentElement)
  File "/usr/lib/tinyos/nesdoc/components.py", line 91, in generate_component
    ht.pdoc(idoc)
  File "/usr/lib/tinyos/nesdoc/html.py", line 149, in pdoc
    self.p(self.escape_email(val))
  File "/usr/lib/tinyos/nesdoc/html.py", line 51, in p
    self.f.write(s)
UnicodeEncodeError: 'ascii' codec can't encode characters in position 2-3: ordinal not in range(128)


As done above, edit the html.py file with the following: 

--- /usr/lib/tinyos/nesdoc/html_old.py
+++ /usr/lib/tinyos/nesdoc/html.py
@@ -48,7 +48,7 @@
     if self.at0:
       self.f.write(" " * self.ind)
       self.at0 = False
-    self.f.write(s)
+    self.f.write(s.encode('utf-8'))

   # print a string and end the line
   def pln(self, s): 

Afterwards the documentation can be viewed and navegated through by browsing the generated index.html file at $TOSROOT/doc/nesdoc/platform:

Nesdoc output: components, interfaces and wirings