Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README: Re-wrap and improve formatting #189

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

README: Re-wrap and improve formatting #189

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 68 additions & 61 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,23 @@ SymPy Online Shell
.. image:: https://travis-ci.org/sympy/sympy-live.svg?branch=master
:target: https://travis-ci.org/sympy/sympy-live

Online Shell for SymPy (sympy-live) is a simple web application based on
Google App Engine, which allows to evaluate Python code with SymPy in web
Online Shell for SymPy (sympy-live) is a simple web application based on Google
App Engine (GAE), which allows to evaluate Python code with SymPy in web
browsers.

This is accomplished by providing a HTML/JavaScript GUI for entering source
code and visualization of output, and a server part which evaluates the
requested source code. Note that this shell is not scalable and it uses
only one instance on GAE, thus all evaluation requests are queued and it
may take quite a lot of time, before our code can be evaluated (depending
on the current load of the instance).
This is accomplished by providing a HTML/JavaScript GUI for entering source code
and visualization of output, and a server part which evaluates the requested
source code. Note that this shell is not scalable and it uses only one instance
on GAE, thus all evaluation requests are queued and it may take quite a lot of
time, before our code can be evaluated (depending on the current load of the
instance).

Google App Engine has intrinsic 30 second request handling limit, so each
evaluation request is a subject to this limit. There are also other limits
related to memory consumption, output size, etc. (see Google App Engine
documentation for details).


Installation
------------

Expand All @@ -33,14 +34,15 @@ We use submodules to include external libraries in sympy-live::
$ git submodule init
$ git submodule update

This is sufficient to clone appropriate repositories in correct versions
into sympy-live (see git documentation on submodules for information).
This is sufficient to clone appropriate repositories in correct versions into
sympy-live (see git documentation on submodules for information).


Development Server
------------------

To setup the development environment and run the app locally, you
need ``docker`` and ``docker-compose``:
To setup the development environment and run the app locally, you need
``docker`` and ``docker-compose``:

* https://docs.docker.com/get-docker/
* https://docs.docker.com/compose/install/
Expand All @@ -55,16 +57,17 @@ This will spin up a local server that runs on port ``8080``.
Open a web browser and go to http://localhost:8080.
You should see GUI of SymPy Online Shell.


Deploying to Google App Engine
------------------------------

Travis-CI is used to deploy automatically to the official server
via Github Releases.
Travis-CI is used to deploy automatically to the official server via Github
Releases.

* Go to https://github.com/sympy/sympy-live/releases
* Click on create a release and name the release as `version-NN`
where `NN` is the release version. After this travis will automatically
release version `NN`.
* Click on create a release and name the release as ``version-NN`` where ``NN``
is the release version. After this travis will automatically release version
``NN``.

To upload the application manually, you need to do a few things.
First, tag th current commit with the App Engine application version
Expand All @@ -80,9 +83,9 @@ the google cloud console for the project::

$ gcloud init

You need to to create ``lib`` (libraries) before deploying, make sure the development
server is up and running via ``docker-compose``, as mentioned above and create
libraries folder to package with the following command::
You need to to create ``lib`` (libraries) before deploying, make sure the
development server is up and running via ``docker-compose``, as mentioned above
and create libraries folder to package with the following command::

$ docker cp app:/usr/src/app/lib lib

Expand All @@ -96,12 +99,13 @@ This requires admin privileges to http://sympy-live.appspot.com. If you don't
have access to this App Engine application, but want to test it, see the
instructions in the `Testing on the App Engine`_ section below.

After doing either of the steps (via github release or manually),
go to http://NN.sympy-live.appspot.com, where ``NN`` is the version
you just uploaded (or released), and make sure that it works.
If it does, go to the ``Versions`` section of the sympy-live dashboard,
and set this as the new default version. If there are any issues, you
can roll back to the previous version from this same screen.
After doing either of the steps (via github release or manually), go to
``http://NN.sympy-live.appspot.com``, where ``NN`` is the version you just
uploaded (or released), and make sure that it works.
If it does, go to the ``Versions`` section of the sympy-live dashboard, and set
this as the new default version. If there are any issues, you can roll back to
the previous version from this same screen.


Creating Deployment Credentials
-------------------------------
Expand All @@ -111,12 +115,12 @@ service account for deployment with suitable permissions, follow these steps:

https://cloud.google.com/solutions/continuous-delivery-with-travis-ci#creating_credentials

These are stored encrypted in the ``client-secret.json.enc`` file in the repository, and are generated
using the Travis command-line tools (client-secret.json is the credentials file for the service account
created int the step above) ::

These are stored encrypted in the ``client-secret.json.enc`` file in the
repository, and are generated using the Travis command-line tools
(``client-secret.json`` is the credentials file for the service account created
in the step above)::

travis encrypt-file client-secret.json --add
travis encrypt-file client-secret.json --add

This also adds the encrypted keys in travis environment variables, which you can
check from here: https://travis-ci.org/github/aktech/sympy-live/settings in the
Expand All @@ -129,54 +133,55 @@ Testing on the App Engine
It's usually a good idea to test big changes on the App Engine itself before
deploying, as ``dev_appserver.py`` can only simulate the App Engine.

There is a semi-official testing server at sympy-live-tests.appspot.com. If you want
write access to it, just ask Aaron Meurer. The convention there is to push
There is a semi-official testing server at sympy-live-tests.appspot.com. If you
want write access to it, just ask Aaron Meurer. The convention there is to push
to the version corresponding to the pull request (so if you have a branch that
is pull request #55, you would push to version 55, and access it by
55-dot-sympy-live-tests.appspot.com). Alternately, you can set up your own
``55-dot-sympy-live-tests.appspot.com``). Alternately, you can set up your own
testing server (it's free, though it requires a cell phone to set up).

You need to to create ``lib`` (libraries) before deploying, make sure the development
server is up and running via ``docker-compose``, as mentioned above and create
libraries folder to package with the following command::
You need to to create ``lib`` (libraries) before deploying, make sure the
development server is up and running via ``docker-compose``, as mentioned above
and create libraries folder to package with the following command::

$ docker cp app:/usr/src/app/lib lib


Either way, to test, you will need to edit the Project ID in the deploy command
mentioned above with your Project ID and the version you want to deploy to::

$ gcloud app deploy --project <your-project-name> --no-promote --version <TAGGED_VERSION>


If you have a test app online, remember to update it every time you update a
pull request, so that others can easily review your work, without even having
to use ``dev_appserver.py``.
pull request, so that others can easily review your work, without even having to
use ``dev_appserver.py``.

Branch builds are automatically deployed by Travis to
`https://<BRANCH-NAME>-dot-sympy-live-hrd.appspot.com/`.
Note that branch has to be on this repository, as forks
do not have access to the key to deploy to the app engine,
and branch name should match the regex: ``[0-9a-zA-Z-_]``
(See app.yaml to check out the static files regex) for
the static files to load properly
``https://<BRANCH-NAME>-dot-sympy-live-hrd.appspot.com/``.
Note that branch has to be on this repository, as forks do not have access to
the key to deploy to the app engine, and the branch name should match the regex:
``[0-9a-zA-Z-_]``
(see ``app.yaml`` to check out the static files regex) for the static files to
load properly.


Development notes
-----------------

Make sure SymPy Online Shell works in major mainstream web browsers. This
includes Chrome, Firefox, Safari and Internet Explorer. Be extra cautious
about trailing commas in JavaScript object and arrays. IE doesn't allow
them, so you have to remove them, if any were introduced.
includes Chrome, Firefox, Safari and Internet Explorer. Be extra cautious about
trailing commas in JavaScript object and arrays. IE doesn't allow them, so you
have to remove them, if any were introduced.


Running Tests
-------------

To run tests you need to spinup the container as mentioned above
via ``docker-compose`` and run the following command::
To run tests you need to spinup the container as mentioned above via
``docker-compose`` and run the following command::

$ docker-compose exec app pytest tests/ -v


Pulling changes
---------------

Expand All @@ -188,16 +193,17 @@ in the simplest case. SymPy Live, however, requires additional effort::

$ git submodule update

The above command assures that if there were any changes to submodules
of the super-project, then those submodules will get updated to new
versions. This is related to the following section.
The above command assures that if there were any changes to submodules of the
super-project, then those submodules will get updated to new versions. This is
related to the following section.


Updating SymPy
--------------

Make sure that you followed instructions above and SymPy's submodule is
properly initialized. Assuming that you are in the directory where SymPy
Live was cloned, issue::
Make sure that you followed instructions above and SymPy's submodule is properly
initialized. Assuming that you are in the directory where SymPy Live was cloned,
issue::

$ cd sympy/
$ git fetch origin
Expand Down Expand Up @@ -231,6 +237,7 @@ This was done for SymPy's version 0.7.0, so in future updates of SymPy replace
particular SHA signatures will be different in your case). If unsure, refer to
``git help submodule`` or git book: http://book.git-scm.com/5_submodules.html.


Original info
-------------

Expand All @@ -248,6 +255,6 @@ Interpreter state is stored in the datastore so that variables, function
definitions, and other values in the global and local namespaces can be used
across commands.

To use the shell in your app, copy shell.py, static/*, and templates/* into
your app's source directory. Then, copy the URL handlers from app.yaml into
your app.yaml.
To use the shell in your app, copy ``shell.py``, ``static/*``, and
``templates/*`` into your app's source directory. Then, copy the URL handlers
from ``app.yaml`` into your ``app.yaml``.