Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Closing issue #2.

Documentation has been provided for the updated directory structure.
  • Loading branch information...
commit 77541f61c83016ddc609600db8a029eec3364cc1 1 parent 300c321
@ccotter ccotter authored
View
17 README.markdown
@@ -17,6 +17,7 @@ library.
Currently, the OCW OT API supports Unix-like systems with the following tools.
+* JavaScript platform - for running the OT code itself
* Node.js, npm (optional, for using the OT API with Node.js)
* sphinx docs (optional, for building documentation)
@@ -26,14 +27,30 @@ Application programmers wishing to use the OT API can checkout this project as a
git repository (or submodule into an already existing git repository), or
download the code as a tarball and extract into their project.
+The code is available as a Node.JS module accessible via
+[npm](https://npmjs.org/), module name
+[coweb-jsoe](https://npmjs.org/package/coweb-jsoe).
+
+##Development
+
+This section describes how to setup a development environment to for coweb-jsoe
+development.
+
###Code organization
* `/src` The source code lives here.
+ * `/src/coweb/jsoe` coweb-jsoe OT Engine JavaScript source code
+ * `/src/org/requirejs` Contains the i18n requirejs library. See NOTICES.
+ * `/src/npm` Source for Node.JS module.
* `/docs` Sphinx documentation.
* `/examples` Example code using the OCW OT API.
* `/bin` Scripts to build release versions of the OCW OT API.
* `/dist` Release versions.
+###Building
+
+See `/bin/README` for building release versions of coweb-jsoe.
+
##Usage
###Operational Transform
View
42 bin/README.markdown
@@ -0,0 +1,42 @@
+
+#Building a release version of coweb-jsoe
+
+##Code organization
+
+The source code of the operational transformation algorithm lives in
+`/src/coweb/jsoe`. This code is included in all release packages as it is
+essential to having OT.
+
+The code in `/src/npm` is used to generate a Node.JS module.
+
+The code in `/src/org` is 3rd party library code used by coweb-jsoe. See the
+NOTICES file in the project root directory for licensing information.
+
+##Building
+
+The release packages are generated using scripts in this `/bin` directory. When
+releasing a new version of coweb-jsoe, change all references to version
+numbering. As of writing this README, there are three locations with version
+information: `/src/coweb/jsoe/OperationEngine.js`, `/src/npm/package.json`, and
+`/docs/conf.py`. Change the version number to that of what is about to be released.
+
+###Build coweb-jsoe
+
+The coweb-jsoe target contains only the source code required for creating an
+`OTEngine` JavaScript object. Run `./bin/release-jsoe.sh` from the project root
+directory. The script will warn if the release tarball already exists in `/dist`.
+Use `--force` to overwrite any existing package in `/dist`.
+
+###Build Node.JS coweb-jsoe module
+
+The Node.JS module target is created by running `./bin/release-npm.sh` and works
+similar to the above script. After creating the npm release target, run
+`npm publish dist/npm/coweb-jsoe-$VERSION.tgz` to publish the target to npm's
+central repository.
+
+###Build documentation
+
+You will need the sphinx docs tools for building the documentation. Navigate to
+`/docs` and run `make` to see a list of available options. `make html` will
+create an HTML version of the documentation.
+
View
4 docs/api.rst
@@ -186,7 +186,7 @@ Alice
.. sourcecode:: javascript
/* MyServer is some object that allows Alice to communicate with Bob (not
- provided by this API. */
+ provided by this API). */
var server = new MyServer();
var collabList = [];
var ote = new OTEngine(server.getUniqueId());
@@ -210,7 +210,7 @@ Bob
.. sourcecode:: javascript
/* MyServer is some object that allows Bob to communicate with Alice (not
- provided by this API. */
+ provided by this API).*/
var server = new MyServer();
var collabList = [];
var ote = new OTEngine(server.getUniqueId());
View
4 docs/conf.py
@@ -48,9 +48,9 @@
# built documents.
#
# The short X.Y version.
-version = '0.8.3.1-SNAPSHOT'
+version = '0.8.3'
# The full version, including alpha/beta/rc tags.
-release = '0.8.3.1-SNAPSHOT'
+release = '0.8.3'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
View
9 docs/development.rst
@@ -0,0 +1,9 @@
+
+=====================
+Developing coweb-jsoe
+=====================
+
+See `/bin/README.markdown`_ for information on working on the coweb-jsoe project
+and instructions on building a release version of coweb-jsoe.
+
+.. _/bin/README.markdown: https://github.com/opencoweb/coweb-jsoe/blob/master/bin/README.markdown
View
1  docs/index.rst
@@ -15,6 +15,7 @@ Contents:
api
usage
+ development
.. rubric:: Other Resources
View
10 docs/usage.rst
@@ -13,11 +13,10 @@ Requirements
============
This OT library provides only the
-[operational transform](http://en.wikipedia.org/wiki/Operational_transformation)
-algorithms and exposure to the engine. Communication between remote clients is
-not provided by this library. Thus, the application programmer is responsible
-for the communication mechanism (eg. hosting a central server to ferry data
-between clients).
+`operational transform`_ algorithms and exposure to the engine. Communication
+between remote clients is not provided by this library. Thus, the application
+programmer is responsible for the communication mechanism (eg. hosting a central
+server to ferry data between clients).
Example code is provided that creates a Node.js
server for remote clients to communicate and exchange data, but this is purely
@@ -68,3 +67,4 @@ itself.
It is recommended that each peer distributes its local engine state to remote
peers every **ten** seconds.
+.. _operational transform: http://en.wikipedia.org/wiki/Operational_transformation
Please sign in to comment.
Something went wrong with that request. Please try again.