Author: bugman
Date: Thu Jun 20 16:42:27 2013
New Revision: 20237
URL: http://svn.gna.org/viewcvs/relax?rev=20237&view=rev
Log:
Merged revisions 20231-20236 via svnmerge from
svn+ssh://bugman@xxxxxxxxxxx/svn/relax/trunk
........
r20231 | bugman | 2013-06-20 15:21:06 +0200 (Thu, 20 Jun 2013) | 5 lines
Created a new listings language definition for relax for the user manual.
This is for better highlighting of relax scripts and code in the relax
manual.
........
r20232 | bugman | 2013-06-20 15:43:20 +0200 (Thu, 20 Jun 2013) | 6 lines
Fix for the scons fetch_docstrings target.
The user functions need to be explicitly initialised in the
fetch_docstrings script as this is not
running through relax.
........
r20233 | bugman | 2013-06-20 16:10:00 +0200 (Thu, 20 Jun 2013) | 3 lines
Added an EPS version of the 128x128 J coupling icon for use in the relax
user manual.
........
r20234 | bugman | 2013-06-20 16:14:10 +0200 (Thu, 20 Jun 2013) | 3 lines
Removed some junk text from the relax script text in section 6.3.8 of the
user manual.
........
r20235 | bugman | 2013-06-20 16:21:15 +0200 (Thu, 20 Jun 2013) | 8 lines
The relax language definition is now auto-generated by the
fetch_docstrings.py script.
This is for use in the relax user manual using the listings package. The
fetch_docstrings.py
script now creates the docs/latex/script_definition.tex file. This is used
by the relax.tex file
via an \include{} statement. This setup allows all of the relax user
functions to be dynamically
set as keywords for the relax language definition.
........
r20236 | bugman | 2013-06-20 16:37:03 +0200 (Thu, 20 Jun 2013) | 5 lines
Converted all of the Development chapter of the user manual to use the
listing package.
This is for all of the code examples, which are now much more colourful.
........
Added:
branches/relax_disp/graphics/relax_icons/128x128/j_coupling.eps.gz
- copied unchanged from r20236,
trunk/graphics/relax_icons/128x128/j_coupling.eps.gz
Modified:
branches/relax_disp/ (props changed)
branches/relax_disp/docs/latex/curvefit.tex
branches/relax_disp/docs/latex/develop.tex
branches/relax_disp/docs/latex/fetch_docstrings.py
branches/relax_disp/docs/latex/relax.tex
Propchange: branches/relax_disp/
------------------------------------------------------------------------------
--- svnmerge-integrated (original)
+++ svnmerge-integrated Thu Jun 20 16:42:27 2013
@@ -1,1 +1,1 @@
-/trunk:1-20228
+/trunk:1-20236
Modified: branches/relax_disp/docs/latex/curvefit.tex
URL:
http://svn.gna.org/viewcvs/relax/branches/relax_disp/docs/latex/curvefit.tex?rev=20237&r1=20236&r2=20237&view=diff
==============================================================================
--- branches/relax_disp/docs/latex/curvefit.tex (original)
+++ branches/relax_disp/docs/latex/curvefit.tex Thu Jun 20 16:42:27 2013
@@ -501,7 +501,7 @@
\begin{lstlisting}[firstnumber=95]
# Save the program state.
-\example{state.save(file='rx.save', force=True)
+state.save(file='rx.save', force=True)
\end{lstlisting}
Modified: branches/relax_disp/docs/latex/develop.tex
URL:
http://svn.gna.org/viewcvs/relax/branches/relax_disp/docs/latex/develop.tex?rev=20237&r1=20236&r2=20237&view=diff
==============================================================================
--- branches/relax_disp/docs/latex/develop.tex (original)
+++ branches/relax_disp/docs/latex/develop.tex Thu Jun 20 16:42:27 2013
@@ -79,17 +79,14 @@
An example of a single line docstring is:
-\begin{footnotesize}
-\begin{verbatim}
+\begin{lstlisting}
def delete(self):
"""Function for deleting all model-free data."""
-\end{verbatim}
-\end{footnotesize}
+\end{lstlisting}
An example of a multiline docstring is:
-\begin{footnotesize}
-\begin{verbatim}
+\begin{lstlisting}
def aic(chi2, k, n):
"""Akaike's Information Criteria (AIC).
@@ -109,8 +106,7 @@
"""
return chi2 + 2.0*k
-\end{verbatim}
-\end{footnotesize}
+\end{lstlisting}
In addition to the text descriptions, the docstrings use the
\href{http://epydoc.sourceforge.net/}{Epydoc}\index{epydoc} markup language
to describe arguments, return values, and other information about the code.
See
\href{http://epydoc.sourceforge.net/fields.html}{http://epydoc.sourceforge.net/fields.html}
for a listing of all the epydoc fields allowed. This mark up language is
important for the creation of the \href{http://www.nmr-relax.com/api/}{API
documentation}\index{API documentation} and to help developers understand the
purpose and operation of the code.
@@ -127,8 +123,7 @@
For both variables and functions lower case with underscores between words
is always used. This is for readability as the convention is much more
fluent than camel case. A few rare exceptions exist, an example is the
Brownian diffusion tensor parameter of anisotropy $\Diff_a$ which is
referenced as \prompt{cdp.diff\_tensor.Da}. As a rule though all new
variable or function names should be kept as lower case. An example of this
convention for both the variable name and function name is:
-\begin{footnotesize}
-\begin{verbatim}
+\begin{lstlisting}
def assemble_param_vector(self, spin=None, spin_id=None, sim_index=None,
model_type=None):
"""Assemble the model-free parameter vector (as numpy array).
@@ -140,8 +135,7 @@
@type spin_id: str
@keyword sim_index: The optional MC simulation index.
@type sim_index: int
- @keyword model_type: The optional parameter set, one of 'all',
'diff', 'mf', or
- 'local_tm'.
+ @keyword model_type: The optional parameter set, one of 'all',
'diff', 'mf', or 'local_tm'.
@type model_type: str or None
@return: An array of the parameter values of the
model-free model.
@rtype: numpy array
@@ -161,8 +155,7 @@
# Spherical diffusion.
if cdp.diff_tensor.type == 'sphere':
param_vector.append(cdp.diff_tensor.tm)
-\end{verbatim}
-\end{footnotesize}
+\end{lstlisting}
@@ -171,8 +164,7 @@
For classes relax uses a mix of camel case (for example all the
\prompt{RelaxError} objects) and underscores (for example
\pycode{Model\_free}). The first letter in all cases is always capitalised.
Generally the camel case is reserved for very low level classes which are
involved in the program's infrastructure. Examples include the RelaxError
code, the threading code, and the relax data store code. All the data
analysis specific code, generic code, interface code, etc.\ uses underscores
between the words with only the first letter capitalised. One exception is
the space mapping class \pycode{OpenDX}, the reason being that the program is
called \prompt{OpenDX}. An example is:
-\begin{footnotesize}
-\begin{verbatim}
+\begin{lstlisting}
class Model_free_main:
"""Class containing functions specific to model-free analysis."""
@@ -181,17 +173,14 @@
@param spin: The spin container object.
@type spin: SpinContainer instance
- @return: The name of the first parameter in the parameter
list in which the
- corresponding parameter value is None. If all
parameters are set, then None
- is returned.
+ @return: The name of the first parameter in the parameter
list in which the corresponding parameter value is None. If all parameters
are set, then None is returned.
@rtype: str or None
"""
# Deselected residue.
if spin.select == 0:
return
-\end{verbatim}
-\end{footnotesize}
+\end{lstlisting}
@@ -216,14 +205,11 @@
\end{itemize}
An example which shows most of these conventions is:
-\begin{footnotesize}
-\begin{verbatim*}
+\begin{lstlisting}
class Internal:
"""The internal relax structural data object.
- The structural data object for this class is a container possessing a
number of different arrays
- corresponding to different structural information. These objects are
described in the
- structural container docstring.
+ The structural data object for this class is a container possessing a
number of different arrays corresponding to different structural information.
These objects are described in the structural container docstring.
"""
def _bonded_atom(self, attached_atom, index, mol):
@@ -247,8 +233,7 @@
# Determine the molecule type if needed.
if not hasattr(mol, 'type'):
self._mol_type(mol)
-\end{verbatim*}
-\end{footnotesize}
+\end{lstlisting}
Modified: branches/relax_disp/docs/latex/fetch_docstrings.py
URL:
http://svn.gna.org/viewcvs/relax/branches/relax_disp/docs/latex/fetch_docstrings.py?rev=20237&r1=20236&r2=20237&view=diff
==============================================================================
--- branches/relax_disp/docs/latex/fetch_docstrings.py (original)
+++ branches/relax_disp/docs/latex/fetch_docstrings.py Thu Jun 20 16:42:27
2013
@@ -23,6 +23,8 @@
"""User function definition conversion to LaTeX for the relax manual."""
# Python module imports.
+from os import sep
+from os.path import dirname
from re import search
from string import ascii_letters, ascii_lowercase, punctuation, whitespace
import sys
@@ -33,8 +35,13 @@
# relax module imports.
from graphics import fetch_icon
+import user_functions
from user_functions.data import Uf_info; uf_info = Uf_info()
from user_functions.data import Uf_tables; uf_tables = Uf_tables()
+
+
+# Set up the user functions.
+user_functions.initialise()
class Fetch_docstrings:
@@ -45,6 +52,7 @@
self.in_quote = False
self.table_count = 1
self.uf_table_labels = []
+ self.path = dirname(file)
# Set up the words to index.
self.index_entries()
@@ -53,7 +61,10 @@
self.file = open(file, 'w')
# Loop over the user functions.
+ uf_names = []
for self.uf_name, self.uf in uf_info.uf_loop():
+ # Add to the list.
+ uf_names.append(self.uf_name)
# The user function class.
self.uf_class = None
if search('\.', self.uf_name):
@@ -78,6 +89,9 @@
# Close the LaTeX file.
self.file.close()
+
+ # Create the relax lstlisting definition.
+ self.script_definitions(uf_names)
def break_functions(self, text):
@@ -735,6 +749,92 @@
# Return the string.
return string
+
+
+ def script_definitions(self, uf_names):
+ """Create a LaTeX file defining the relax language syntax for the
listings package.
+
+ @param uf_names: The list of all user function names.
+ @type uf_names: list of str
+ """
+
+ # Open the file.
+ file = open(self.path + sep + 'script_definition.tex', 'w')
+
+ # Python keywords.
+ py_keywords = [
+ 'and',
+ 'assert',
+ 'break',
+ 'continue',
+ 'del',
+ 'else',
+ 'exec',
+ 'global',
+ 'if',
+ 'in',
+ 'is',
+ 'for',
+ 'not',
+ 'or',
+ 'pass',
+ 'print',
+ 'raise',
+ 'return',
+ 'while',
+ 'yield'
+ ]
+ py_keywords2 = [
+ 'as',
+ 'from',
+ 'import',
+ ]
+ py_keywords3 = [
+ 'class',
+ 'def',
+ ]
+
+ # The relax language.
+ file.write("\lstdefinelanguage{relax}{\n")
+
+ # Allow the user function '.' character to be part of the keywords.
+ file.write(" alsoletter={.},\n")
+
+ # Output the first set of Python keywords.
+ file.write(" morekeywords={")
+ for name in py_keywords:
+ file.write("%s," % name)
+ file.write("},\n")
+
+ # Output the second set of Python keywords.
+ file.write(" morekeywords=[2]{")
+ for name in py_keywords2:
+ file.write("%s," % name)
+ file.write("},\n")
+
+ # Output the third set of Python keywords.
+ file.write(" morekeywords=[3]{")
+ for name in py_keywords3:
+ file.write("%s," % name)
+ file.write("},\n")
+
+ # Output the relax user functions as keywords.
+ file.write(" morekeywords=[4]{")
+ for name in uf_names:
+ file.write("%s," % name)
+ file.write("},\n")
+
+ # The rest of the definition.
+ file.write(" moreprocnamekeys={def,class},\n")
+ file.write(" sensitive=true,\n")
+ file.write(" morecomment=[l]{\#},\n")
+ file.write(" morestring=[b]',\n")
+ file.write(" morestring=[b]\",\n")
+ file.write(" morestring=[b]\"\"\",\n")
+ file.write("}\n")
+
+ # Close the file.
+ file.close()
def tabular_wrapping(self, table, max_char=100):
Modified: branches/relax_disp/docs/latex/relax.tex
URL:
http://svn.gna.org/viewcvs/relax/branches/relax_disp/docs/latex/relax.tex?rev=20237&r1=20236&r2=20237&view=diff
==============================================================================
--- branches/relax_disp/docs/latex/relax.tex (original)
+++ branches/relax_disp/docs/latex/relax.tex Thu Jun 20 16:42:27 2013
@@ -40,9 +40,10 @@
urlcolor=blue}
% Source code and scripts.
-\usepackage{listings}
+\usepackage[procnames]{listings}
\usepackage[svgnames]{xcolor}
\usepackage{textcomp}
+\include{script_definition}
\lstset{
backgroundcolor=\color{white},
basewidth=0.5em,
@@ -51,23 +52,26 @@
breaklines=true,
captionpos=b,
columns=fixed,
- commentstyle=\color{blue},
+ commentstyle=\color{Blue},
frame=none,
keepspaces=true,
keywordstyle=\bfseries \color{ForestGreen},
- language=Python,
+ keywordstyle=[2]\bfseries \color{BlueViolet},
+ keywordstyle=[3]\bfseries \color{SaddleBrown},
+ keywordstyle=[4]\bfseries \color{MidnightBlue},
+ language=relax,
numbers=left,
numbersep=15pt,
- numberstyle=\tiny \color{orange},
+ numberstyle=\tiny \color{DarkOrange},
+ procnamestyle=\color{LightSeaGreen},
showspaces=false,
showstringspaces=false,
showtabs=false,
stepnumber=1,
- stringstyle=\color{Crimson},
+ stringstyle=\color{FireBrick},
tabsize=4,
upquote=true,
}
-
% New commands.
\newcommand{\example}[1]{\vspace{-1ex} \sloppy{\footnotesize \texttt{#1}}}
r20237 - in /branches/relax_disp: ./ docs/latex/ graphics/relax_icons/128x128/