Bug 1423 - extend create-module.py to generate documentation outline

src/create-module.py

@@ -210,6 +210,80 @@ static %(CAPITALIZED)sTestSuite %(MODULE)sTestSuite;
 '''
 
 
+DOC_RST_TEMPLATE = '''Example Module Documentation
+----------------------------
+
+.. heading hierarchy:
+   ------------- Chapter
+   ************* Section (#.#)
+   ============= Subsection (#.#.#)
+   ############# Paragraph (no number)
+
+This is a suggested outline for adding new module documentation to ns-3.
+See ``src/click/doc/click.rst`` for an example.
+
+The introductory paragraph is for describing what this code is trying to
+model.
+
+Model Description
+*****************
+
+The source code for the new module lives in the directory ``src/%(MODULE)s``.
+
+Design
+======
+
+Add here an overall description of the software design and how it fits
+into the existing ns-3 architecture. 
+
+Scope and Limitations
+=====================
+
+What can the model do?  What can it not do?  Please use this section to
+describe the scope and limitations of the model.
+
+References
+==========
+
+Add academic citations here, such as if you published a paper on this
+model, or if readers should read a particular specification or other work.
+
+Usage
+*****
+
+This section is principally concerned with the usage of your model, using
+the public API.
+
+Building New Module
+===================
+
+Include this section if there are special build instructions.
+
+Helper
+======
+
+What helper API will users typically use?  Describe it here.
+
+Advanced Usage
+==============
+
+Go into further details (such as using the API outside of the helpers)
+in additional sections, as needed.
+
+Examples
+========
+
+What examples using this new code are available?  Describe them here.
+
+Validation
+**********
+
+Describe how the model has been tested/validated.  What tests run in the
+test suite?  How much API and code is covered by the tests?  Again, 
+references to outside published work may help here.
+'''
+
+
 def main(argv):
     parser = OptionParser(usage=("Usage: %prog [options] modulename\n"
                                  "Utility script to create a basic template for a new ns-3 module"))
@@ -274,7 +348,9 @@ def main(argv):
     helper_h.write(HELPER_H_TEMPLATE % dict(MODULE=modname, INCLUDE_GUARD="__%s_HELPER_H__" % (modname.upper()),))
     helper_h.close()
 
-
+    #
+    # examples
+    #
     examplesdir = os.path.join(moduledir, "examples")
     os.mkdir(examplesdir)
 
@@ -286,6 +362,16 @@ def main(argv):
     example_cc.write(EXAMPLE_CC_TEMPLATE % dict(MODULE=modname))
     example_cc.close()
 
+    #
+    # doc
+    # 
+    docdir = os.path.join(moduledir, "doc")
+    os.mkdir(docdir)
+
+    doc_rst = file(os.path.join(moduledir, "doc", "%s.rst" % modname), "wt")
+    doc_rst.write(DOC_RST_TEMPLATE % dict(MODULE=modname))
+    doc_rst.close()
+
 
     return 0