Author: bugman
Date: Sun Jun 3 12:40:27 2012
New Revision: 16606
URL: http://svn.gna.org/viewcvs/relax?rev=16606&view=rev
Log:
Complete rewrite of the docs.latex.fetch_docstrings module (accidentally
partly committed at r16596).
This is a significant simplification for the creating of the user function
documentation within the
user manual. Some of the long list of changes include:
- The file docs/latex/fetch_docstrings.py is no longer an executable script
and now operates solely
as a Python module.
- All of the original docstring section parsing code has been eliminated.
The searching for user
functions in the prompt UI namespace has been replaced
- The new user function definitions are directly used and the documentation
for each user function
section generated via the self.build_*() methods.
- The complicated ascii table parsing and rebuilding into a LaTeX table has
been eliminated.
- The self.write_*() methods have been created for building the various
sections of the user
function documentation (paragraphs, verbatim text, prompt examples, lists,
itemised lists, and
tables).
- Tables are no longer duplicated, triplicated, etc. Instead a reference to
the first instance of
the table is inserted. This is a significant space saver, as one of the
copies of the multi-page
X11 colour table is removed.
Modified:
branches/uf_redesign/docs/latex/fetch_docstrings.py
branches/uf_redesign/docs/latex/relax.tex
Modified: branches/uf_redesign/docs/latex/fetch_docstrings.py
URL:
http://svn.gna.org/viewcvs/relax/branches/uf_redesign/docs/latex/fetch_docstrings.py?rev=16606&r1=16605&r2=16606&view=diff
==============================================================================
--- branches/uf_redesign/docs/latex/fetch_docstrings.py (original)
+++ branches/uf_redesign/docs/latex/fetch_docstrings.py Sun Jun 3 12:40:27
2012
@@ -21,9 +21,8 @@
###############################################################################
# Python module imports.
-from inspect import formatargspec, getargspec, getdoc
from re import search
-from string import letters, lowercase, lstrip, punctuation, replace, rstrip,
split, upper, whitespace
+from string import letters, lowercase, punctuation, replace, split, upper,
whitespace
import sys
# Add the path to the relax base directory.
@@ -32,6 +31,7 @@
# Import the program relax.
from user_functions.data import Uf_info; uf_info = Uf_info()
+from user_functions.data import Uf_tables; uf_tables = Uf_tables()
class Fetch_docstrings:
@@ -41,6 +41,7 @@
# Initialise some variables.
self.in_quote = False
self.table_count = 1
+ self.uf_table_labels = []
# Set up the words to index.
self.index_entries()
@@ -399,9 +400,6 @@
def latex_formatting(self, string):
"""Function for handling LaTeX maths environments."""
-
- # FIXME: delete.
- return string
# Angstrom.
string = self.safe_replacement(string, 'Angstroms', '\AA')
@@ -596,33 +594,6 @@
return string
- def num_to_text(self, num):
- """Convert the number to text.
- @param num: The number to convert.
- @type num: int
- @return: The number in the format of 'First', 'Second', 'Third',
etc.
- @rtype: str
- """
-
- # The list.
- list = ['First',
- 'Second',
- 'Third',
- 'Fourth',
- 'Fifth',
- 'Sixth',
- 'Seventh',
- 'Eighth',
- 'Ninth',
- 'Tenth',
- 'Eleventh',
- 'Twelfth'
- ]
-
- # Convert.
- return list[num-1]
-
-
def quotes(self, index):
"""Function for placing quotes within the quote environment."""
@@ -913,46 +884,69 @@
self.file.write("\n")
- def write_table(self, table):
+ def write_table(self, label):
"""Format and write out a table.
- @param table: The table.
- @type table: list of lists of str
+ @param label: The unique table label.
+ @type label: list of lists of str
"""
+ # Get the table.
+ table = uf_tables.get_table(label)
+
# Add a reference.
- self.file.write("Please see Table~\\ref{table%s}.\n\n" %
self.table_count)
+ self.file.write("Please see Table~\\ref{%s} on
page~\\pageref{%s}.\n\n" % (label, label))
+
+ # The table already exists, so skip creating it a second time.
+ if label in self.uf_table_labels:
+ return
+ else:
+ self.uf_table_labels.append(label)
# Determine the table wrapping.
- col_wrap = self.tabular_wrapping(table)
+ col_wrap = self.tabular_wrapping(table.cells)
wrap = sum(col_wrap)
+ # The number of rows and columns.
+ num_rows = len(table.cells)
+ num_cols = len(table.headings)
+
# Start the centred table.
- self.file.write("\\begin{table*}\n")
- self.file.write("\\begin{scriptsize}\n")
- self.file.write("\\begin{center}\n")
+ if table.longtable:
+ # A longtable.
+ self.file.write("\\onecolumn\n")
+ self.file.write("\\begin{scriptsize}\n")
+ self.file.write("\\begin{center}\n")
+ self.file.write("\\begin{longtable}{%s}\n" % ("l"*num_cols))
+ else:
+ # Normal tables.
+ self.file.write("\\begin{table*}\n")
+ self.file.write("\\begin{scriptsize}\n")
+ self.file.write("\\begin{center}\n")
# A caption.
- self.file.write("\\caption{%s table for the %s user function.}\n" %
(self.num_to_text(self.uf_table_count), self.uf_name_latex))
-
- # The number of rows and columns.
- num_rows = len(table)
- num_cols = len(table[0])
-
- # Start the tabular environment and add the toprule.
- if wrap:
- self.file.write("\\begin{tabularx}{\\textwidth}{")
+ self.file.write("\\caption[%s]{%s}\n" % (table.caption_short,
table.caption))
+
+ # The formatting.
+ if table.longtable:
+ # Start the longtable environment and add the toprule.
+ self.file.write("\\\\\n")
+ self.file.write("\\toprule\n")
else:
- self.file.write("\\begin{tabular}{")
- for i in range(num_cols):
- if col_wrap[i]:
- text = "X"
+ # Start the tabular environment and add the toprule.
+ if wrap:
+ self.file.write("\\begin{tabularx}{\\textwidth}{")
else:
- text = "l"
- self.file.write(text)
- self.file.write("}\n")
- self.file.write("\\\\[-5pt]")
- self.file.write("\\toprule\n")
+ self.file.write("\\begin{tabular}{")
+ for i in range(num_cols):
+ if col_wrap[i]:
+ text = "X"
+ else:
+ text = "l"
+ self.file.write(text)
+ self.file.write("}\n")
+ self.file.write("\\\\[-5pt]\n")
+ self.file.write("\\toprule\n")
# Generate the LaTeX headings.
for j in range(num_cols):
@@ -961,7 +955,7 @@
self.file.write(' & ')
# The cell contents.
- cell = table[0][j]
+ cell = table.headings[j]
cell = self.latex_special_chars(cell)
cell = self.latex_formatting(cell)
@@ -971,11 +965,22 @@
# End of the header line.
self.file.write(" \\\\\n")
- # Add the midrule.
- self.file.write("\\midrule\n")
+ # The central formatting.
+ if table.longtable:
+ self.file.write("\\midrule\n")
+ self.file.write("\\endhead\n\n")
+ self.file.write("\\bottomrule\n")
+ self.file.write("\\endfoot\n")
+ else:
+ # Add the midrule.
+ self.file.write("\\midrule\n")
+
+ # The label for longtables.
+ if table.longtable:
+ self.file.write("\\label{%s}\n" % label)
# Loop over the main table lines.
- for i in range(1, num_rows):
+ for i in range(num_rows):
# Loop over the columns.
for j in range(num_cols):
# Column separator.
@@ -983,7 +988,7 @@
self.file.write(' & ')
# The cell contents.
- cell = table[i][j]
+ cell = table.cells[i][j]
cell = self.latex_special_chars(cell)
cell = self.latex_formatting(cell)
@@ -994,16 +999,22 @@
self.file.write(" \\\\\n")
# Terminate.
- self.file.write("\\bottomrule\n")
- self.file.write("\\\\[-5pt]")
- self.file.write("\\label{table%s}\n" % self.table_count)
- if wrap:
- self.file.write("\\end{tabularx}\n")
+ if table.longtable:
+ self.file.write("\\end{longtable}\n")
+ self.file.write("\\end{center}\n")
+ self.file.write("\\end{scriptsize}\n")
+ self.file.write("\\twocolumn\n")
else:
- self.file.write("\\end{tabular}\n")
- self.file.write("\\end{center}\n")
- self.file.write("\\end{scriptsize}\n")
- self.file.write("\\end{table*}\n")
+ self.file.write("\\bottomrule\n")
+ self.file.write("\\\\[-5pt]\n")
+ self.file.write("\\label{%s}\n" % label)
+ if wrap:
+ self.file.write("\\end{tabularx}\n")
+ else:
+ self.file.write("\\end{tabular}\n")
+ self.file.write("\\end{center}\n")
+ self.file.write("\\end{scriptsize}\n")
+ self.file.write("\\end{table*}\n")
# Increment the table counts.
self.table_count += 1
Modified: branches/uf_redesign/docs/latex/relax.tex
URL:
http://svn.gna.org/viewcvs/relax/branches/uf_redesign/docs/latex/relax.tex?rev=16606&r1=16605&r2=16606&view=diff
==============================================================================
--- branches/uf_redesign/docs/latex/relax.tex (original)
+++ branches/uf_redesign/docs/latex/relax.tex Sun Jun 3 12:40:27 2012
@@ -10,9 +10,9 @@
\usepackage{makeidx}
% Good looking tables.
-\usepackage{tabularx}
\usepackage{booktabs}
\usepackage{longtable}
+\usepackage{tabularx}
% Obliterate those painful LaTeX margins!
\usepackage{vmargin}
@@ -143,7 +143,8 @@
% List of Tables.
%%%%%%%%%%%%%%%%%
-%\listoftables
+\newpage
+\listoftables
% Abbreviations.
@@ -196,17 +197,17 @@
% The chapters.
%%%%%%%%%%%%%%%
-%\include{intro}
-%\include{install}
-%\include{infrastruct}
-%\include{noe}
-%\include{curvefit}
-%\include{model-free}
-%\include{jw_mapping}
-%\include{maths}
-%\include{develop}
+\include{intro}
+\include{install}
+\include{infrastruct}
+\include{noe}
+\include{curvefit}
+\include{model-free}
+\include{jw_mapping}
+\include{maths}
+\include{develop}
\include{functions}
-%\include{licence}
+\include{licence}
% End of the main chapters.
r16606 - in /branches/uf_redesign/docs/latex: fetch_docstrings.py relax.tex