docs: fix typos

[cassella]

FYI, I got here by following the link from the recently-posted blog post, which linked to readthedocs.io. There are some strange formatting things going on there:

http://pychapel.readthedocs.io/usage_examples.html

There are two sorts of weirdness going on:

1. Some of the large blocks of included source are truncated (at least in my browser). For example, usage_example.rst's first block of test_finance_python_numpy.py specifies lines: 1-92. On readthedocs.io, I see lines 1-72 included, and lines 73-92 as blank.

I don't know what's going on here, or how to test a fix.

2. Some of the line numbers specified in the .rst files don't seem right. For example, in the above case, I'd think it should include through line 95. The next few blocks included in usage_examples.rst don't look right either, starting a few lines before the function the text is describing, or cutting off before the end.

I can guess that in these cases, lines have been added or removed from the .py files, but the .rst files have not been updated. I can guess at fixes for them, but I still don't know how to test that they would improve the rendering.

[lydia-duncan]

I can't see why the build failed because it seems like there is something up with Travis. I'll check back in on that later.

In the meanwhile, I suspect you are right about the .rst file not having been updated when .py files were, my bad. There's a make doc command at the top level of the repository, you should be able to use that to generate a version of the html and ensure any changes made there are correct.

[lydia-duncan]

You are welcome to commit a fix for that as well, otherwise I will probably take care of it once Travis starts working again.

[cassella]

make doc fails with

...
reading sources... [100%] usage_other                                                                                                                     

Warning, treated as error:
/home/fortytwo/src/pychapel/docs/source/pych/array_ops.rst:4: WARNING: autodoc: failed to import module u'pych.array_ops'; the following exception was raised:
Traceback (most recent call last):
  File "/home/fortytwo/.local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 518, in import_object
    __import__(self.modname)
ImportError: No module named pych.array_ops

Makefile:53: recipe for target 'html' failed
...

I presume because I didn't follow the pyChapel installation instructions. (I cloned the repo only to fix the typos, not to try pyChapel...)

But I can't follow the installation instructions either; pip install --user pyChapel fails at

...
  running install_data
  creating build/bdist.linux-x86_64/wheel/pyChapel-0.1.17.data
  creating build/bdist.linux-x86_64/wheel/pyChapel-0.1.17.data/data
  creating build/bdist.linux-x86_64/wheel/pyChapel-0.1.17.data/data/share
  creating build/bdist.linux-x86_64/wheel/pyChapel-0.1.17.data/data/share/pych
  creating build/bdist.linux-x86_64/wheel/pyChapel-0.1.17.data/data/share/pych/config
  error: can't copy 'configs/pych.json': doesn't exist or not a regular file

  ----------------------------------------
  Failed building wheel for pyChapel
  Running setup.py clean for pyChapel
Failed to build pyChapel
Installing collected packages: pyChapel
  Running setup.py install for pyChapel ... error
...
    byte-compiling /home/fortytwo/.local/lib/python2.7/site-packages/pych/__init__.py to __init__.pyc
    running install_data
    error: can't copy 'configs/pych.json': doesn't exist or not a regular file
...

Ubuntu 16.04.2 LTS

[cassella]

I repushed the same commit to try to retry the CI build. It still failed,

...
2017-05-31 03:11:39 [INFO] Running py.test over /home/travis/build/chapel-lang/pychapel/module/testing and doc examples

Traceback (most recent call last):
  File "/home/travis/virtualenv/python2.7.9/bin/py.test", line 9, in <module>
    load_entry_point('pytest==2.6.4', 'console_scripts', 'py.test')()
  File "/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/_pytest/config.py", line 32, in main
    config = _prepareconfig(args, plugins)
  File "/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/_pytest/config.py", line 85, in _prepareconfig
    pluginmanager=pluginmanager, args=args)
  File "/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/_pytest/core.py", line 413, in __call__
    return self._docall(methods, kwargs)
  File "/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/_pytest/core.py", line 424, in _docall
    res = mc.execute()
  File "/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/_pytest/core.py", line 315, in execute
    res = method(**kwargs)
  File "/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/_pytest/helpconfig.py", line 27, in pytest_cmdline_parse
    config = __multicall__.execute()
  File "/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/_pytest/core.py", line 315, in execute
    res = method(**kwargs)
  File "/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/_pytest/config.py", line 636, in pytest_cmdline_parse
    self.parse(args)
  File "/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/_pytest/config.py", line 747, in parse
    self._preparse(args)
  File "/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/_pytest/config.py", line 714, in _preparse
    self.pluginmanager.consider_setuptools_entrypoints()
  File "/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/_pytest/core.py", line 179, in consider_setuptools_entrypoints
    plugin = ep.load()
  File "/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/pkg_resources/__init__.py", line 2309, in load
    self.require(*args, **kwargs)
  File "/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/pkg_resources/__init__.py", line 2326, in require
    items = working_set.resolve(reqs, env, installer)
  File "/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/pkg_resources/__init__.py", line 810, in resolve
    raise VersionConflict(dist, req).with_context(dependent_req)
pkg_resources.VersionConflict: (pytest 2.6.4 (/home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages), Requirement.parse('pytest>=2.7.0'))

The command "./util/test_python.bash" exited with 1.

[lydia-duncan]

I think the reason I can't see the Travis build might be my version of firefox or something.

Also, pip install pyChapel is probably going to try to download the repo from pip, not install from your local copy, so I don't think you'll be able to test your changes that way . . .

[cassella]

Ah. I was guessing that make doc was failing because I hadn't followed the pyChapel installation instructions, so I was blindly doing what introduction.rst said to do.

Ah, and I hadn't included the make doc failure:

...
reading sources... [100%] usage_other

Warning, treated as error:
/home/fortytwo/src/pychapel/docs/source/pych/array_ops.rst:4: WARNING: autodoc: failed to import module u'pych.array_ops'; the following exception was raised:
Traceback (most recent call last):
  File "/home/fortytwo/.local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 518, in import_object
    __import__(self.modname)
ImportError: No module named pych.array_ops

Makefile:53: recipe for target 'html' failed
...

[lydia-duncan]

Since pych is one of the pyChapel modules, I believe that you are correct it is complaining because you haven't installed pyChapel. @kushalsingh007 had an issue with Ubuntu and the config file, but I don't know how he got around it

[lydia-duncan]

I'm suspecting an out of date version for some of the package repositories on which pyChapel relies, though I don't know why it would fail for Travis but not in our nightly pyChapel builds . . .

[lydia-duncan]

Okay, that's just weird. The latest version of pytest is 3.1.1 and our requirements file doesn't lock us in to a particular version of pytest so it really should be downloading the latest version instead of getting 2.6.4. Lemme look at the Travis build more closely

[lydia-duncan]

Okay, so apparently Travis already has pytest installed on it, so when it tries to install the pytest dependency it finds the version it already has and thinks that is good enough, but it isn't. I'm going to open a separate PR to try and fix that

[lydia-duncan]

I've merged a change that ought to fix your build issue - I restarted the last Travis run on this PR to see if you need to merge the change in or not (hopefully not). You are also able to restart Travis builds if you log in with your Github account, should it come up again.

[cassella]

You are also able to restart Travis builds if you log in with your Github account, should it come up again.

I thought I should be able to, but I couldn't find the right thing to click on last night. :-/ Thanks!