Author: bugman
Date: Thu May 31 15:49:03 2012
New Revision: 16559
URL: http://svn.gna.org/viewcvs/relax?rev=16559&view=rev
Log:
Started to redesign the user function definition descriptions.
The desc object has been converted into a list which will contain instances
of the new
Desc_container class. This class will hold the description information as
blocks of text, including
unformatted paragraphs, verbatim text, lists, tables, and relax prompt
examples. The object has a
number of methods used for inputting all of the information, as well as
extracting it.
The information in the Desc_container object is not formatted, for example
tables will be stored as
lists of lists. This will remove the need for parsing list, tables, verbatim
text, etc. by the
docs.latex.fetch_docstrings module. But these will need to be recreated for
the prompt help
strings, for the GUI user function descriptions, and for the user manual.
Modified:
branches/uf_redesign/user_functions/objects.py
Modified: branches/uf_redesign/user_functions/objects.py
URL:
http://svn.gna.org/viewcvs/relax/branches/uf_redesign/user_functions/objects.py?rev=16559&r1=16558&r2=16559&view=diff
==============================================================================
--- branches/uf_redesign/user_functions/objects.py (original)
+++ branches/uf_redesign/user_functions/objects.py Thu May 31 15:49:03 2012
@@ -78,6 +78,130 @@
class Container:
"""An empty container object."""
+
+
+
+class Desc_container(object):
+ """A special object for holding and processing user function description
information."""
+
+ def __init__(self, title="Description"):
+ """Set up the container.
+
+ @keyword section: The section title.
+ @type section: str
+ """
+
+ # Store the title.
+ self._title = title
+
+ # Initialise internal storage objects.
+ self._data = []
+ self._types = []
+
+
+ def add_list_element(self, text):
+ """Add the element of a list to the description.
+
+ @param text: The list element text.
+ @type text: str
+ """
+
+ # Store the text.
+ self._data.append(text)
+ self._types.append('list')
+
+
+ def add_paragraph(self, text):
+ """Add a paragraph of text to the description.
+
+ @param text: The paragraph text.
+ @type text: str
+ """
+
+ # Store the text.
+ self._data.append(text)
+ self._types.append('paragraph')
+
+
+ def add_prompt(self, text):
+ """Add the text of a relax prompt example to the description.
+
+ @param text: The relax prompt text.
+ @type text: str
+ """
+
+ # Create a block if needed.
+ if self._types[-1] != 'prompt':
+ self._data.append([text])
+ self._types.append('prompt')
+
+ # Append the example to an existing example block.
+ else:
+ self._data[-1].append(text)
+
+
+ def add_table_titles(self, titles):
+ """Add a row of table titles to the description.
+
+ @param text: The table titles.
+ @type text: list of str
+ """
+
+ # Create a new table.
+ self._data.append([titles])
+ self._types.append('table')
+
+
+ def add_table_row(self, row):
+ """Add a table row to the description.
+
+ @param text: The table row.
+ @type text: list of str
+ """
+
+ # Create a new table if needed.
+ if self._types[-1] != 'table' or len(row) != len(self._data[-1][-1]):
+ self._data.append([row])
+ self._types.append('table')
+
+ # Append the row to an existing table.
+ else:
+ self._data[-1].append(row)
+
+
+ def add_verbatim(self, text):
+ """Add a section of verbatim text to the description.
+
+ @param text: The verbatim text.
+ @type text: str
+ """
+
+ # Store the text.
+ self._data.append(text)
+ self._types.append('verbatim')
+
+
+ def element_loop(self):
+ """Iterator method yielding the description elements.
+
+ @return: The element type and corresponding data.
+ @rtype: str and anything
+ """
+
+ # Loop over the elements.
+ for i in range(len(self._data)):
+ yield self._types[i], self._data[i]
+
+
+ def get_title(self):
+ """Return the title of the section.
+
+ @return: The section title.
+ @rtype: str
+ """
+
+ # The title.
+ return self._title
@@ -94,8 +218,8 @@
@type backend: executable object
@ivar display: A flag specifying if the user function
displays output to STDOUT. This is used for certain UIs to display that
output.
@type display: str
- @ivar desc: The full, multi-paragraph description.
- @type desc: str
+ @ivar desc: The multi-paragraph description defined via
the Desc_container class.
+ @type desc: list of Desc_container instances
@ivar additional: Additional documentation, usually appended
to the end of the description.
@type additional: list of str
@ivar prompt_examples: The examples of how to use the prompt front
end.
@@ -145,7 +269,7 @@
self.kargs = []
self.backend = None
self.display = False
- self.desc = None
+ self.desc = []
self.additional = None
self.prompt_examples = None
self.menu_text = ''
r16559 - /branches/uf_redesign/user_functions/objects.py