started working on auto-generated plugin documentation

.hgignore

@@ -1,10 +1,11 @@
 # Documentation
-^doc/doxygen/.*$
+^doc/apidocs/.*$
 ^doc/.*\.aux$
 ^doc/.*\.log$
 ^doc/.*\.out$
 ^doc/.*\.pdf$
 ^doc/.*\.toc$
+^doc/plugins_generated.tex$
 
 # Build-related
 ^\.sconf_temp/.*$

doc/Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NUMBER         = 0.2.0
 # If a relative path is entered, it will be relative to the location 
 # where doxygen was started. If left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = doc/doxygen
+OUTPUT_DIRECTORY       = doc/apidocs
 
 # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 
 # 4096 sub-directories (in 2 levels) under the output directory of each output 
@@ -789,7 +789,7 @@ GENERATE_HTML          = YES
 # If a relative path is entered the value of OUTPUT_DIRECTORY will be 
 # put in front of it. If left blank `html' will be used as the default path.
 
-HTML_OUTPUT            = html
+HTML_OUTPUT            = .
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for 
 # each generated HTML page (for example: .htm,.php,.asp). If it is left blank 
@@ -1198,7 +1198,7 @@ MAN_LINKS              = NO
 # generate an XML file that captures the structure of 
 # the code including all documentation.
 
-GENERATE_XML           = YES
+GENERATE_XML           = NO
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. 
 # If a relative path is entered the value of OUTPUT_DIRECTORY will be 

doc/gendoc.py

@@ -0,0 +1,48 @@
+#! /usr/bin/python
+# 
+# This script walks through all plugin files and 
+# extracts documentation that should go into the
+# reference manual
+
+import os, re
+
+def process(target, filename):
+	f = open(filename)
+	inheader = False
+	for line in f.readlines():
+		match = re.match(r'^/\*!(.*)$', line)
+		if match != None:
+			print("Processing %s" % filename)
+			line = match.group(1).replace('%', '\%')
+			target.write(line + '\n')
+			inheader = True
+			continue
+		if not inheader:
+			continue
+		if re.search(r'^[\s\*]*\*/$', line):
+			inheader = False
+			continue
+		match = re.match(r'^\s*\**(.*)$', line)
+		if match != None:
+			line = match.group(1).replace('%', '\%')
+			target.write(line + '\n')
+	f.close()
+
+# Traverse all source directories and find any plugin code
+def traverse(target, dirname, files):
+	suffix = os.path.split(dirname)[1]
+	if 'lib' in suffix or suffix == 'tests' \
+		or suffix == 'mitsuba' or suffix == 'utils' \
+		or suffix == 'converter' or suffix == 'qtgui':
+		return
+
+	for filename in files:
+		if '.cpp' == os.path.splitext(filename)[1]:
+			process(target,os.path.join(dirname, filename))
+
+os.chdir(os.path.dirname(__file__))
+f = open('plugins_generated.tex', 'w')
+f.write('\section{Plugin reference}\n')
+os.path.walk('../src', traverse, f)
+f.close()
+os.system('pdflatex main.tex')

doc/main.tex

@@ -62,9 +62,12 @@
 % Cite a figure/listing
 \newcommand{\cfig}[1]{\mbox{Figure \ref{fig:#1}}}
 \newcommand{\clst}[1]{\mbox{Listing \ref{lst:#1}}}
-
 \newcommand{\code}[1]{\texttt{#1}}
 
+% Macros for plugin documentation
+\newcommand{\plugin}[2]{\subsection{#2 (\texttt{#1})}\label{plg:#1}}
+\newcommand{\pluginref}[1]{\texttt{\hyperref[plg:#1]{#1}}}
+
 % Listings settings
 \lstset{
 	mathescape = true,
@@ -107,16 +110,16 @@
 
 \tableofcontents
 
-\include{introduction}
+%\include{introduction}
-\include{compiling}
+%\include{compiling}
-\include{basics}
+%\include{basics}
-\include{format}
+%\include{format}
-\include{plugins}
+\IfFileExists{plugins_generated.tex}{\include{plugins_generated}}{}
-\include{import}
+%\include{import}
-\include{development}
+%\include{development}
-\include{integrator}
+%\include{integrator}
-\include{parallelization}
+%\include{parallelization}
-\include{acknowledgements}
+%\include{acknowledgements}
 
 
 \end{document}

doc/plugins.tex

@@ -1,2 +0,0 @@
-\section{Plugin reference}
-TBD

src/bsdfs/lambertian.cpp

@@ -23,19 +23,23 @@
 
 MTS_NAMESPACE_BEGIN
 
-/*!
+/*! \plugin{lambertian}{Ideally diffuse / Lambertian material}
-The Lambertian material represents a one-sided ideal diffuse material
+ * 
-with the specified amount of reflectance. Optionally, a texture map may
+ * The Lambertian material represents an ideally diffuse material
-be applied. If no extra information is provided, the material will revert to 
+ * with the specified amount of reflectance. When nothing is specified,
-the default of uniform 50% reflectance.
+ * the default of 50% reflectance is used.
-
+ *
-Seen from the back side, this material will appear completely black.
+ * Optionally, a texture map may be applied. 
-
+ *
-\verbatim
+ * Note that this material is one-sided --- that is, observed from the 
-<bsdf type="lambertian">
+ * back side, it will be completely black. If this is undesirable, 
-    <srgb name="reflectance" value="#a4da85"/>
+ * consider using the \pluginref{twosided} BRDF adapter plugin.
-</bsdf>
+ *
-\endverbatim
+ * \begin{xml}
+ * <bsdf type="lambertian">
+ *   <srgb name="reflectance" value="#a4da85"/>
+ * </bsdf>
+ * \end{xml}
  */
 class Lambertian : public BSDF {
 public:

src/bsdfs/twosided.cpp

@@ -22,10 +22,16 @@
 
 MTS_NAMESPACE_BEGIN
 
-/**
+/*! \plugin{twosided}{Two-sided BRDF adapter}
- * Turns a one-sided BRDF onto a two-sided one that
+ * 
- * can be used to render meshes where the back-side
+ * Turns a nested one-sided BRDF onto a two-sided version that
- * is visible.
+ * can be used to render meshes where the back-side is visible.
+ *
+ * \begin{xml}
+ * <bsdf type="twosided">
+ *   <bsdf type="lambertian"/>
+ * </bsdf>
+ * \end{xml}
  */
 class TwoSidedBRDF : public BSDF {
 public: