Commits

Anonymous committed 939fbdc

added sample.rst and spreadsheet.rst and improved to the document.
also added doctest and fixed bugs in `ListLike`.

Comments (0)

Files changed (6)

 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['rstspreadsheet']
+extensions = ['rstspreadsheet', 'sphinx.ext.autodoc']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
+highlight_language = 'rst'
+
 
 # -- Options for HTML output ---------------------------------------------------
 
-Welcome to reStructuredSpreadsheet's documentation!
-===================================================
+============================================
+ Welcome to rstSpreadsheet's documentation!
+============================================
 
+Install/Usage
+=============
+::
 
-Usage
-=====
+    pip install rstspreadsheet  # or
+    easy_install rstspreadsheet
 
-Use as a standalone program::
+Or just `download rstspreadsheet.py`_ and put it in the same
+directory as Sphinx's `conf.py`.  To use in Sphinx, put the following
+in your `conf.py`.
 
-    python -m rstspreadsheet sample.rst sample.html
-
-Or use as sphinx extension by adding it to `extensions`::
+.. sourcecode:: python
 
     extensions = [
         # other extensions...
         'rstspreadsheet']
 
 
-Examples
-========
+You can also use it as a standalone program::
 
-Simple spreadsheet
-------------------
+    python -m rstspreadsheet sample.rst sample.html  # or
+    python rstspreadsheet.py sample.rst sample.html
 
-.. spreadsheet:: Simple spreadsheet
-   :eq: {2} = {0} and {1}
-        {3} = int(not {2})
+If you want sample document, `please find sample.rst here`_.
 
-   === === =========== =================
-    p   q    p and q     not (p and q)
-   === === =========== =================
-    0   0
-    1   0
-    0   1
-    1   1
-   === === =========== =================
 
-.. sourcecode:: rst
+.. _`download rstspreadsheet.py`:
+   https://bitbucket.org/tkf/restructured-spreadsheet/raw/tip/rstspreadsheet.py
 
-   .. spreadsheet:: Simple spreadsheet
-      :eq: {2} = {0} and {1}
-           {3} = int(not {2})
+.. _`please find sample.rst here`:
+   https://bitbucket.org/tkf/restructured-spreadsheet/raw/tip/doc/sample.rst
 
-      === === =========== =================
-       p   q    p and q     not (p and q)
-      === === =========== =================
-       0   0
-       1   0
-       0   1
-       1   1
-      === === =========== =================
 
+Other contents
+==============
 
-Spreadsheet with python functions
----------------------------------
+.. toctree::
+   :maxdepth: 1
+   :glob:
 
-.. spreadsheet:: Spreadsheet with python functions
-   :eq: {2} = '{0}({1})'
-        {3} = {2}
-   :setup: from math import sin, cos, exp, pi
-           def fac(n):
-               return fac(n-1) * n if n > 1 else 1
-   :format: 3:'%0.2f'
-
-   ======== ======== ========== ======
-   function argument expression result
-   ======== ======== ========== ======
-   fac      5
-   sin      pi
-   cos      pi
-   exp      1
-   ======== ======== ========== ======
-
-.. sourcecode:: rst
-
-   .. spreadsheet:: Spreadsheet with python functions
-      :eq: {2} = '{0}({1})'
-           {3} = {2}
-      :setup: from math import sin, cos, exp, pi
-              def fac(n):
-                  return fac(n-1) * n if n > 1 else 1
-      :format: 3:'%0.2f'
-
-      ======== ======== ========== ======
-      function argument expression result
-      ======== ======== ========== ======
-      fac      5
-      sin      pi
-      cos      pi
-      exp      1
-      ======== ======== ========== ======
-
-
-Special variables
------------------
-
-.. spreadsheet:: Use of the special variables
-   :eq: {1} = i
-        {2} = last
-        {3} = i == last
-        {4} = sum(col.int) + 1
-
-   == == ====== =========== ==================
-   #  i  last   i == last   sum(col.int) + 1
-   == == ====== =========== ==================
-   0
-   1
-   2
-   3
-   == == ====== =========== ==================
-
-.. sourcecode:: rst
-
-   .. spreadsheet:: Use of the special variables
-      :eq: {1} = i
-           {2} = last
-           {3} = i == last
-           {4} = sum(col.int) + 1
-
-      == == ====== =========== ==================
-      #  i  last   i == last   sum(col.int) + 1
-      == == ====== =========== ==================
-      0
-      1
-      2
-      3
-      == == ====== =========== ==================
-
-
-Conditions
-----------
-
-.. spreadsheet:: Use of condition
-   :eq: {1:i==0} = 3
-        {1:0<i<last} = col.int[-1] + 1
-        {1:i==last} = sum(col.int)
-
-   ======== ===============
-   #        increment/sum
-   ======== ===============
-   0
-   1
-   2
-   sum
-   ======== ===============
-
-.. sourcecode:: rst
-
-   .. spreadsheet:: Use of condition
-      :eq: {1:i==0} = 3
-           {1:0<i<last} = col.int[-1] + 1
-           {1:i==last} = sum(col.int)
-
-      ======== ===============
-      #        increment/sum
-      ======== ===============
-      0
-      1
-      2
-      sum
-      ======== ===============
-
-
-Error handling
---------------
-
-Error in ``:setup:``
-^^^^^^^^^^^^^^^^^^^^
-
-This is the example of the error handling in ``:setup:`` option:
-
-    .. spreadsheet::
-       :eq: {1} = {0}
-       :setup: this is error!
-
-       == ==
-       i  j
-       == ==
-       0
-       1
-       2
-       == ==
-
-.. sourcecode:: rst
-
-   .. spreadsheet::
-      :eq: {1} = {0}
-      :setup: this is error!
-
-      == ==
-      i  j
-      == ==
-      0
-      1
-      2
-      == ==
-
-Error in ``:eq:``
-^^^^^^^^^^^^^^^^^
-
-This is the example of the error handling in ``:eq:`` option:
-
-    .. spreadsheet::
-       :eq: {1} = this is error!
-            {1:this is error, too} = 1
-
-       == ==
-       i  j
-       == ==
-       0
-       == ==
-
-.. sourcecode:: rst
-
-   .. spreadsheet::
-      :eq: {1} = {0}
-           {1:this is error, too} = 1
-
-      == ==
-      i  j
-      == ==
-      0
-      == ==
+   sample
+   spreadsheet
+Example usages of the `spreadsheet` directive
+=============================================
+
+You can also try this example using the standalone command::
+
+    python rstspreadsheet.py sample.rst sample.html
+
+
+Simple spreadsheet
+------------------
+::
+
+    .. spreadsheet:: Simple spreadsheet
+       :eq: {2} = {0} and {1}
+            {3} = int(not {2})
+
+       === === =========== =================
+        p   q    p and q     not (p and q)
+       === === =========== =================
+        0   0
+        1   0
+        0   1
+        1   1
+       === === =========== =================
+
+.. spreadsheet:: Simple spreadsheet
+   :eq: {2} = {0} and {1}
+        {3} = int(not {2})
+
+   === === =========== =================
+    p   q    p and q     not (p and q)
+   === === =========== =================
+    0   0
+    1   0
+    0   1
+    1   1
+   === === =========== =================
+
+
+Spreadsheet with python functions
+---------------------------------
+::
+
+    .. spreadsheet:: Spreadsheet with python functions
+       :eq: {2} = '{0}({1})'
+            {3} = {2}
+       :setup: from math import sin, cos, exp, pi
+               def fac(n):
+                   return fac(n-1) * n if n > 1 else 1
+       :format: 3:'%0.2f'
+
+       ======== ======== ========== ======
+       function argument expression result
+       ======== ======== ========== ======
+       fac      5
+       sin      pi
+       cos      pi
+       exp      1
+       ======== ======== ========== ======
+
+.. spreadsheet:: Spreadsheet with python functions
+   :eq: {2} = '{0}({1})'
+        {3} = {2}
+   :setup: from math import sin, cos, exp, pi
+           def fac(n):
+               return fac(n-1) * n if n > 1 else 1
+   :format: 3:'%0.2f'
+
+   ======== ======== ========== ======
+   function argument expression result
+   ======== ======== ========== ======
+   fac      5
+   sin      pi
+   cos      pi
+   exp      1
+   ======== ======== ========== ======
+
+
+Special variables
+-----------------
+::
+
+    .. spreadsheet:: Use of the special variables
+       :eq: {1} = i
+            {2} = last
+            {3} = i == last
+            {4} = sum(col.int) + 1
+            {5} = cols[0].int
+
+       == == ====== =========== ================== =============
+       #  i  last   i == last   sum(col.int) + 1   cols[0].int
+       == == ====== =========== ================== =============
+       0
+       1
+       2
+       3
+       == == ====== =========== ================== =============
+
+.. spreadsheet:: Use of the special variables
+   :eq: {1} = i
+        {2} = last
+        {3} = i == last
+        {4} = sum(col.int) + 1
+        {5} = cols[0].int
+
+   == == ====== =========== ================== =============
+   #  i  last   i == last   sum(col.int) + 1   cols[0].int
+   == == ====== =========== ================== =============
+   0
+   1
+   2
+   3
+   == == ====== =========== ================== =============
+
+
+Conditions
+----------
+::
+
+    .. spreadsheet:: Use of condition
+       :eq: {1:i==0} = 3
+            {1:0<i<last} = col.int[-1] + 1
+            {1:i==last} = sum(col.int)
+
+       ======== ===============
+       #        increment/sum
+       ======== ===============
+       0
+       1
+       2
+       sum
+       ======== ===============
+
+.. spreadsheet:: Use of condition
+   :eq: {1:i==0} = 3
+        {1:0<i<last} = col.int[-1] + 1
+        {1:i==last} = sum(col.int)
+
+   ======== ===============
+   #        increment/sum
+   ======== ===============
+   0
+   1
+   2
+   sum
+   ======== ===============
+
+
+Error handling
+--------------
+
+Error in ``:setup:``
+^^^^^^^^^^^^^^^^^^^^
+::
+
+    .. spreadsheet::
+       :eq: {1} = {0}
+       :setup: this is error!
+
+       == ==
+       i  j
+       == ==
+       0
+       1
+       2
+       == ==
+
+.. spreadsheet::
+   :eq: {1} = {0}
+   :setup: this is error!
+
+   == ==
+   i  j
+   == ==
+   0
+   1
+   2
+   == ==
+
+Error in ``:eq:``
+^^^^^^^^^^^^^^^^^
+::
+
+    .. spreadsheet::
+       :eq: {1} = {0}
+            {1:this is error, too} = 1
+
+       == ==
+       i  j
+       == ==
+       0
+       == ==
+
+.. spreadsheet::
+   :eq: {1} = this is error!
+        {1:this is error, too} = 1
+
+   == ==
+   i  j
+   == ==
+   0
+   == ==
+The :rst:dir:`spreadsheet` directive
+====================================
+
+.. rst:directive:: .. spreadsheet:: [title]
+
+   eq : cell equations
+       A :ref:`cell-eq` per each line.
+   setup : python code (optional)
+       Python code to be executed before evaluation cell equations.
+   format : number: fmt [, number: fmt, ...] (optional)
+       Comma separated list of the pair of `number` and `format`
+       for showing the result of the cell equation.
+
+.. _cell-eq:
+
+Cell equation
+=============
+
+Cell equation has the shape like this::
+
+    {NUM} = STATEMENT
+
+or::
+
+    {NUM:CONDITION} = STATEMENT
+
+
+More precisely, the syntax of the cell equation is the following:
+
+.. productionlist::
+   eq: `lhs` "=" `rhs`
+   lhs: "{" integer [ ":" `condition` ] "}"
+   rhs: expression_stmt
+   condition: expression_stmt
+
+
+Special variables
+=================
+rstSpreadsheet provides the following special variables.
+You can use these in the cell equation.
+Note that you can override these variables by variables in `:setup:`.
+
+.. py:data:: col
+
+   This stores the *above* cells of the current column.
+   Thus, `col[-1]` means the previous cell.
+
+   .. autoclass:: rstspreadsheet.ListLike
+      :members: str, int, float, sum, mean
+
+.. py:data:: cols
+
+   A variable to access all :py:data`col`.
+   If the current column is 1, `col` is as same as `cols[1]`.
+
+.. py:data:: i
+
+   Index of the current row.
+
+.. py:data:: last
+
+   Index of the last row.  This is useful in the :token:`condition`.
+
+   .. sourcecode:: python
+
+      {1:i<last} = i
+      {1:i==last} = sum(col.int)
 
 class ListLike(object):
     """
-    A class for iterative with convenient cast functions
+    An iterative class with convenient cast functions
 
     >>> col = ListLike(['1', '2', '3'])
     >>> col
         if data is None:
             self._data = []
         else:
-            self._data = data
+            self._data = list(data)
 
     def __repr__(self):
         return '{0}({1!r})'.format(self.__class__.__name__, self._data)
 
     def __getitem__(self, key):
+        """
+        >>> col = ListLike(['1', '2', '3'])
+        >>> col[0]
+        '1'
+        """
         return self._data[key]
 
     def __iter__(self):
+        """
+        >>> col = ListLike(['1', '2', '3'])
+        >>> list(col)
+        ['1', '2', '3']
+        """
         return iter(self._data)
 
     def __contains__(self, item):
+        """
+        >>> col = ListLike(['1', '2', '3'])
+        >>> '1' in col
+        True
+        """
         return item in self._data
 
     def __reversed__(self):
+        """
+        >>> reversed(ListLike(['1', '2', '3']))
+        ListLike(['3', '2', '1'])
+        """
         return ListLike(reversed(self._data))
 
+    def __len__(self):
+        """
+        >>> col = ListLike(['1', '2', '3'])
+        >>> len(col)
+        3
+        """
+        return len(self._data)
+
     def append(self, val):
+        """
+        >>> col = ListLike(['1', '2', '3'])
+        >>> col.append('4')
+        >>> col
+        ListLike(['1', '2', '3', '4'])
+        """
         self._data.append(val)
 
     @property
     def str(self):
+        """Access the stored data as a list of strings (original data)"""
         return self._data
 
     @property
     def int(self):
+        """Access the stored data as a list of ints"""
         return map(int, self._data)
 
     @property
     def float(self):
+        """Access the stored data as a list of floats"""
         return map(float, self._data)
 
+    def sum(self, type='float'):
+        """
+        Get the sum of the stored data
+
+        >>> col = ListLike(['1', '2', '3'])
+        >>> col.sum('int')
+        6
+
+        """
+        return sum(getattr(self, type))
+
+    def mean(self):
+        """
+        Get the mean of the stored data
+
+        >>> col = ListLike(['1', '2', '3'])
+        >>> col.mean()
+        2.0
+
+        """
+        return self.sum('float') / len(self)
+
 
 _RE_EQ_LHS = re.compile(
     r"\{(?P<col>[^\:\}]*)(\:(?P<cond>[^\:\}]*))?\} *= *(?P<eq>.*) *")

sample.rst

-The `spreadsheet` directive examples
-====================================
-
-You can try this example by executing::
-
-    python rstspreadsheet.py sample.rst sample.html
-
-
-Simple spreadsheet
-------------------
-
-.. spreadsheet:: Simple spreadsheet
-   :eq: {2} = {0} and {1}
-        {3} = int(not {2})
-
-   === === ========= =============
-    p   q   p and q  not (p and q)
-   === === ========= =============
-    0   0
-    1   0
-    0   1
-    1   1
-   === === ========= =============
-
-::
-
-    .. spreadsheet:: Simple spreadsheet
-       :eq: {2} = {0} and {1}
-            {3} = int(not {2})
-
-       === === ========= =============
-        p   q   p and q  not (p and q)
-       === === ========= =============
-        0   0
-        1   0
-        0   1
-        1   1
-       === === ========= =============
-
-
-Spreadsheet with python functions
----------------------------------
-
-.. spreadsheet:: Spreadsheet with python functions
-   :eq: {2} = '{0}({1})'
-        {3} = {2}
-   :setup: from math import sin, cos, exp, pi
-           def fac(n):
-               return fac(n-1) * n if n > 1 else 1
-   :format: 3:'%0.2f'
-
-   ======== ======== ========== ======
-   function argument expression result
-   ======== ======== ========== ======
-   fac      5
-   sin      pi
-   cos      pi
-   exp      1
-   ======== ======== ========== ======
-
-::
-
-    .. spreadsheet:: Spreadsheet with python functions
-       :eq: {2} = '{0}({1})'
-            {3} = {2}
-       :setup: from math import sin, cos, exp, pi
-               def fac(n):
-                   return fac(n-1) * n if n > 1 else 1
-       :format: 3:'%0.2f'
-
-       ======== ======== ========== ======
-       function argument expression result
-       ======== ======== ========== ======
-       fac      5
-       sin      pi
-       cos      pi
-       exp      1
-       ======== ======== ========== ======