docs: Make line-limited literalincludes less fragile

Particularly, harden them against code motion.

Use :end-before: instead of line numbers to stop the full program
listings before the test routines.  To this end, add a sentinel
comment line to the python programs where the literalinclude should
end.

Use the :pyobject: line-selection helper in the one case it applies --
the pure python quant().  It can't be used for the Chapel version
because it won't include the leading @chapel() with our current pinned
version of sphinx 1.3.6; fixed by sphinx-doc/sphinx#3348

The test_finance_chapel_numpy.py file that includes the @chapel()
quant is not included as a full file anywhere, only for this one
function and an import line, so use sentinel lines for those too.

docs/source/examples/test_c_inline.py

@@ -18,6 +18,7 @@ def add_ints(x=int, y=int):
 if __name__ == "__main__":
     print(add_doubles(1.0, 3.0))
     print(add_ints(1,2))
+    # End of program marker for usage_other.rst
 
 def test_c_inline():
     assert add_doubles(1.0, 3.0) == 4.0

docs/source/examples/test_c_synthetic_numpy.py

@@ -66,6 +66,7 @@ def main(tsteps, particles):
     args = parser.parse_args()
 
     main(args.tsteps, args.particles)
+    # End of program marker for usage_examples.rst
 
 import testcase
 # contains the general testing method, which allows us to gather output

docs/source/examples/test_chapel_synthetic_numpy.py

@@ -48,6 +48,7 @@ def main(tsteps, particles):
     args = parser.parse_args()
 
     main(args.tsteps, args.particles)
+    # End of program marker for usage_examples.rst
 
 import testcase
 # contains the general testing method, which allows us to gather output

docs/source/examples/test_finance_chapel_numpy.py

@@ -12,7 +12,9 @@
 
 import pytest
 
+# begin marker for import line for usage_examples.rst
 from pych.extern import Chapel
+# end marker for import line for usage_examples.rst
 
 elapsed = [time.time()]
 
@@ -60,6 +62,7 @@ def load_prices(filename):
 
     return date, bid, ask, voodoo
 
+# begin pyChapel quant marker for usage_examples.rst
 @Chapel()
 def quant(date=np.ndarray, bid=np.ndarray, ask=np.ndarray, voodoo=np.ndarray):
     """
@@ -73,6 +76,7 @@ def quant(date=np.ndarray, bid=np.ndarray, ask=np.ndarray, voodoo=np.ndarray):
     voodoo = voodoo / future;
     """
     return None
+# end pyChapel quant marker for usage_examples.rst
 
 def main(filename, with_viz=True):
     date, bid, ask, voodoo = load_prices(filename)      # Load dataset

docs/source/examples/test_finance_python_numpy.py

@@ -94,6 +94,7 @@ def main(filename, with_viz=True):
     args = parser.parse_args()
     R = main(args.filename, not args.no_viz)
     print(R.sum())
+    # End of program marker for usage_examples.rst
 
 import testcase
 # contains the general testing method, which allows us to gather output

docs/source/examples/test_python_synthetic_numpy.py

@@ -48,6 +48,7 @@ def main(tsteps, particles):
     args = parser.parse_args()
 
     main(args.tsteps, args.particles)
+    # End of program marker for usage_examples.rst
 
 import testcase
 # contains the general testing method, which allows us to gather output

docs/source/usage_examples.rst

@@ -26,7 +26,7 @@ An example of such an application is provided below:
 .. literalinclude:: /examples/test_finance_python_numpy.py
    :language: python
    :linenos:
-   :lines: 1-96
+   :end-before: End of program marker
 
 Where the computationally intensive part is the function
 ``quant``. Do note that the specific implementation of the ``quant`` function
@@ -35,19 +35,21 @@ Using ``pych`` this function can be mapped to Chapel by changing:
 
 .. literalinclude:: /examples/test_finance_python_numpy.py
    :language: python
-   :lines: 62-71
+   :pyobject: quant
 
 to:
 
 .. literalinclude:: /examples/test_finance_chapel_numpy.py
    :language: python
-   :lines: 63-75
+   :start-after: begin pyChapel quant
+   :end-before: end pyChapel quant
 
 and adding the include statement:
 
 .. literalinclude:: /examples/test_finance_chapel_numpy.py
    :language: python
-   :lines: 15-15
+   :start-after: begin marker for import
+   :end-before: end marker for import
 
 .. note:: Chapel's array implementation currently requires that sparsely
           packed numpy arrays be *flattened* before sending them to any
@@ -93,7 +95,7 @@ An example of such an application is provided below:
 .. literalinclude:: /examples/test_python_synthetic_numpy.py
    :language: python
    :linenos:
-   :lines: 1-50
+   :end-before: End of program marker
 
 where the time-consuming, computational expensive, and memory hungry portion of
 the application is the data-processing performed in the `simulation` function.
@@ -107,7 +109,7 @@ such as the example below illustrates:
 .. literalinclude:: /examples/test_chapel_synthetic_numpy.py
    :language: python
    :linenos:
-   :lines: 1-50
+   :end-before: End of program marker
 
 These two implementations can be executed by the commands::
 
@@ -136,5 +138,5 @@ C-Implementation
 .. literalinclude:: /examples/test_c_synthetic_numpy.py
    :language: python
    :linenos:
-   :lines: 1-68
+   :end-before: End of program marker
 

docs/source/usage_other.rst

@@ -11,5 +11,5 @@ Bla bla use pyChapel to dynamically compile c-code.
 
 .. literalinclude:: /examples/test_c_inline.py
    :language: python
-   :lines: 1-20
+   :end-before: End of program marker