diff --git a/conceptnet b/conceptnet index c08bf29..c570fc3 160000 --- a/conceptnet +++ b/conceptnet @@ -1 +1 @@ -Subproject commit c08bf29d079b9c30f353d781296900c950696bb9 +Subproject commit c570fc31890bef49a915e7d3597aeae0d9682292 diff --git a/divisi2 b/divisi2 index ac55752..7d882bb 160000 --- a/divisi2 +++ b/divisi2 @@ -1 +1 @@ -Subproject commit ac55752506b694c5b9b1cacdcf7651bd5b5018d4 +Subproject commit 7d882bb7d50dd7228e1755c4a31343451bc5724f diff --git a/docs/developers/bzr-howto.rst b/docs/developers/bzr-howto.rst deleted file mode 100644 index 1b585d6..0000000 --- a/docs/developers/bzr-howto.rst +++ /dev/null @@ -1,145 +0,0 @@ -Common Sense Computing and Bazaar -================================= - -`Bazaar`_ is a version control system, much like Subversion or the ancient CVS. -The advantage of Bazaar is that it lets you make your own "branch" of the code, -where you can make and undo changes while not interfering with anyone else's -code, but you can also stay up to date with the main "trunk" of the code. - -The `official Bazaar documentation`_ is actually quite good, but we've -made this document as a shorter summary of the things we found we -needed. Feel free to suggest more things! - -.. _`Bazaar`: http://bazaar-vcs.org/ -.. _`official Bazaar documentation`: http://bazaar-vcs.org/Documentation - -First-time setup ----------------- -* Install Bazaar (http://bazaar-vcs.org/) or on Ubuntu:: - - sudo aptitude install bzr - -* Sign up for Launchpad (http://launchpad.net/) -* Join the Commonsense Computing team (http://launchpad.net/~commonsense) -* Register an SSH public key with Launchpad: - - * If you run the `ssh-keygen` command on Linux or Mac, this will give you a public key in the file `~/.ssh/id_rsa.pub`. - * Go to https://launchpad.net/+me/+editsshkeys and insert the contents of that file. - -* Tell Bazaar about your Launchpad id:: - - bzr launchpad-login myusername - -Working on a project --------------------- - -Start by making a branch of the project you're working on:: - - bzr branch lp:conceptnet my_conceptnet_branch - -(This gives you a local working directory called ``my_conceptnet_branch``.) - -*Hack vigorously...* - -If you create new files, add them:: - - bzr add filename - -Commit often, usually for every major step you take (you'll be glad later):: - - bzr status # make sure there's no new files you meant to add - bzr commit -m "this is my highly informative commit message" - -This commits to *your* version-controlled repository. It can't mess with anyone else. It's safe. - -When new things happen on the trunk, you can get your branch up to date by -*pulling* those changes:: - - bzr pull lp:conceptnet - -However, if you've committed things to your branch, you have to *merge* the -upstream changes with your own:: - - bzr merge lp:conceptnet # get your branch up to date with what's changed - bzr commit -m "Merged" - -When it's ready for prime time, push it back into the trunk:: - - bzr push lp:conceptnet - -If the trunk has changes you haven't merged, you'll need to merge before you can push. - - -I don't want my own branch, I just want to use this like SVN ------------------------------------------------------------- - -Okay. This makes perfect sense for a quick change, but if you make a habit of this you're probably going to get in someone's way. - -Instead of branching, get a *checkout*:: - - bzr checkout lp:conceptnet - -A checkout is a working copy whose repository is somewhere else. When you commit, it commits to that repository. This is how everything worked in Subversion. - -To pull in new stuff from the repository:: - - bzr update - -To commit your changes to the repository:: - - bzr commit -m "extremely informative message" - -Checking out the same branch somewhere else -------------------------------------------- -You've made a branch on one computer, and you want to work with the same branch -on another computer. No problem. Make a checkout of it:: - - bzr checkout bzr+ssh://your.host.name/path/to/your/branch - -Now you have multiple checkouts of the same branch, and you can update, commit, etc. just like above. - -This also makes sense if you want to work on some minor branch that's on Launchpad (like ``lp:~commonsense/conceptnet/new-caledonia``) without re-branching it. Check out that branch and commit to it. - - -Sharing a branch ----------------- -Are you doing cool stuff that we want to see, but isn't ready to go into the -trunk? You can host your branch on Launchpad where others can see it. -Here's how to do that:: - - bzr push lp:~username/project/branch-name - -For example, Rob might do this:: - - bzr push lp:~rspeer/conceptnet/speed-up-the-lemmatizer - -That's right, you can just make up a URL like that and suddenly Launchpad is -hosting a branch for you. Now "bind" your branch to that new hosted branch:: - - bzr bind lp:~username/project/branch-name - -The ``bzr bind`` command means that your directory becomes a *checkout* instead -of a *branch*; when you ``commit`` or ``update``, you will do so by talking to -Launchpad. It's slower, but now your code is accessible from anywhere (and -backed up, too). - - -I screwed up! What do I do? ---------------------------- -If you committed something you didn't mean to, you can fix it:: - - bzr uncommit - -(This *does* work even on a checkout of a remote branch, but if anyone -has pulled from it since you committed, they might not be happy with -you. Honestly I haven't tried it.) - -If you added something you meant to be unversioned:: - - bzr remove --keep filename - -If you want to go back to a previous revision, look up how to use ``bzr revert --r`` to revert to an earlier revision. - -If you pushed to somewhere you didn't mean to, check out that branch and revert it back to something sane. - diff --git a/docs/developers/contributions.rst b/docs/developers/contributions.rst index 7a6f896..9ece917 100644 --- a/docs/developers/contributions.rst +++ b/docs/developers/contributions.rst @@ -5,16 +5,23 @@ Open Mind is an open source project. If you see something you can improve in the code, we encourage you to share your improvement with us so we can include it in future versions. -Pushing code to Launchpad +GitHub branches and forks ------------------------- -As a developer, you have presumably checked out our code from Launchpad. The -first step in sharing your improvements is to push your branch back to -Launchpad, under your own name. So for example, if your Launchpad username is -jbloggs, and you have an improvement to Divisi that makes SVDs faster, you -could push it to Launchpad with:: - - bzr push lp:~jbloggs/divisi/make-svds-faster +As a developer, you have presumably checked out our code from GitHub. GitHub +makes it very easy to "fork" a project -- that's not as disruptive as it +sounds, it's just hosting a copy of the project under your own GitHub account. +In the fork, you can make whatever changes you want, you can pull our later +updates, and we can pull your updates when we want to include them in the main +repository. + +Instructions on forking are at: http://help.github.com/forking/ + + +If you work closely with us, you may have access to the main repositories under +"commonsense/". In that case, you don't have to make a complete fork; you can +just make a new branch where you make your changes. +http://progit.org/book/ch3-0.html is a very helpful guide to branching. Letting Commonsense Computing redistribute your code ---------------------------------------------------- @@ -42,7 +49,7 @@ just get to redistribute your code. You will be credited for your contributions in the source code. How does this compare to other open source projects? ----------------------------------------------------- +.................................................... Our terms for contributors are most similar to the Qt_ project. Their contributors have to sign a `contribution agreement`_ very similar to this one. diff --git a/docs/developers/index.rst b/docs/developers/index.rst index 3fbb6ed..40e3f94 100644 --- a/docs/developers/index.rst +++ b/docs/developers/index.rst @@ -9,7 +9,6 @@ Contents: .. toctree:: :maxdepth: 2 - bzr-howto setup karma contributions diff --git a/docs/developers/karma.rst b/docs/developers/karma.rst index e32b260..36e9dc2 100644 --- a/docs/developers/karma.rst +++ b/docs/developers/karma.rst @@ -26,15 +26,13 @@ package. Writing docstrings for functions you use, or for new functions you have written, is an easy form of coding karma. These docstrings can easily be included in more complete documentation later. -The documentation repository ----------------------------- - -We have a documentation repository. In fact, you're *reading* the output of the -documentation repository right now. +The documentation directory +--------------------------- -You can check it out with `bzr checkout lp:~commonsense/cscweb/documentation`. -A plain checkout is probably fine -- there shouldn't be any reason to have -different branches of documentation. +What you're reading right now comes from a directory called "docs" under the +"omcs" Git repository. You can edit it in its checked-out version, or you can +make changes through the Web at +http://github.com/commonsense/omcs/tree/master/docs/. The documentation repository contains a couple of things: @@ -49,12 +47,9 @@ Writing "recipes" If you have an example of accomplishing something useful with our tools, show it to other people! -The `recipes/` directory of the documentation repository is the place to put +The `recipes/` directory of the documentation is the place to put these. They can even be included as pages of the Sphinx documentation later. -Rob's getting this started by including `health_blend.py` in the recipes -directory. - Writing tests ------------- We use `nose` for testing. You can get this program with:: @@ -142,11 +137,11 @@ of the docstrings. If you have access to the docs server, and you have Fabric installed (``easy_install fabric``), you can update the -documentation on the Web site (http://csc.media.mit.edu/doc/) by running:: +documentation on the Web site (http://csc.media.mit.edu/docs/) by running:: - bzr commit + git commit -a fab test - fab update # if the test works + fab update # if the test works "fab update" might crash with an error about setting attributes on files, but if it does, it already got far enough. diff --git a/docs/developers/setup.rst b/docs/developers/setup.rst index f6553ad..da41be1 100644 --- a/docs/developers/setup.rst +++ b/docs/developers/setup.rst @@ -33,9 +33,8 @@ For the next step: .. _linux: -Setting up Linux packages -------------------------- - +Linux setup +----------- On Ubuntu, you can get the required packages with this command:: $ sudo apt-get install python-dev python-setuptools python-pip python-virtualenv build-essential git @@ -48,18 +47,16 @@ That's all for the platform-specific stuff. Go on to :ref:`cross_platform`. .. _mac: -Setting up Mac OS ------------------ +Mac OS setup +------------ If you have OS 10.6, you almost have everything you need. You can use the built-in `easy_install` to get `pip`:: sudo easy_install pip -Then go onto :ref:`_have_mac_pip`. +Then go onto :ref:`have_mac_pip`. -Mac OS 10.5 -........... -The version of Python that is pre-installed in OS 10.5 is insufficient. You'll +On the other hand, if you're on Mac OS 10.5, the version of Python that is pre-installed in OS 10.5 is insufficient. You'll first need to download and install Python 2.6 from http://python.org. Then you need to download Distribute. You can set it up by typing these @@ -73,22 +70,28 @@ Once this runs, go on to the next section. .. _have_mac_pip: Installing other Mac tools --------------------------- - -You can get a NumPy 1.4 installer for the Mac at https://sourceforge.net/projects/numpy/files/. Download and install it, then go on to the next section. +.......................... +You can get a NumPy 1.4 installer for the Mac at https://sourceforge.net/projects/numpy/files/. +Once you download and install it, you can skip to the section called +:ref:`cross_platform`. .. _windows: +Windows setup +------------- +If you already have Python 2.6 and can run it from the command prompt, skip to :ref:`have_windows_python`. Otherwise, continue to the next section. + Setting up Python on Windows ----------------------------- +............................ -- If you already have Python 2.6 and can run it from the command prompt, skip to :ref:`have_windows_python`. -- First, you need to download Python 2.6 from http://python.org, and install it. -- After that, you will need to set it up so that you can use Python from the - command line, by setting the PATH environment variable. Instructions for doing - this are at: http://docs.python.org/using/windows.html#excursus-setting-environment-variables +First, you need to download Python 2.6 from http://python.org, and install it. + +After that, you will need to set it up so that you can use Python from the +command line, by setting the PATH environment variable. Instructions for doing +this are at: +http://docs.python.org/using/windows.html#excursus-setting-environment-variables If you've done all this, you should be able to open a command prompt and type `python`, and get an interactive Python prompt. Once you can do this, go on to @@ -97,14 +100,14 @@ the next step. .. _have_windows_python: Getting NumPy for Windows -------------------------- +......................... Download and install NumPy, from https://sourceforge.net/projects/numpy/files/. Choose the latest Python 2.6 "superpack" version. Type ``import numpy`` at the Python prompt and make sure you don't get an error, and go on to the next step. Getting Distribute/Pip for Windows ----------------------------------- +.................................. Distribute is a system for managing Python packages. Pip is a useful command-line program for downloading and installing packages. @@ -117,7 +120,7 @@ program in C on Windows using Cygwin, you probably would prefer to follow the :ref:`cygwin_directions`. Setting up MinGW and msysgit ----------------------------- +............................ Download and install MinGW from http://www.mingw.org/. This gives you a slightly better command line, and a minimal installation of `gcc`. @@ -134,19 +137,22 @@ You'll also need Git, so download and install msysgit (the official Windows vers Now you're ready to jump to the section on :ref:`install_packages`. Alternate Cygwin directions ---------------------------- +........................... Use Cygwin Setup to install `gcc`, `make`, and `git`. -Using the Cygwin shell, you can follow the directions in the next section and -just leave off the "sudo". I think. I've never tried using virtualenv on -Cygwin. You can also just skip the next section and run without virtual -environments. +Using the Cygwin shell, you can follow the directions in :ref:`cross_platform` +and just leave off the "sudo". I think. I've never tried using virtualenv on +Cygwin. You can also just skip to :ref:`install_packages` and run without +virtual environments. + +Cross-platform directions +------------------------- .. _cross_platform: -Setting up a virtual environment (Linux or Mac) ------------------------------------------------ +Setting up a virtual environment +................................ ``virtualenv`` is a system that sets up an isolated copy of Python for you to develop in. @@ -184,7 +190,7 @@ Now go on to the next section. .. _install_packages: Installing CSC packages and their dependencies ----------------------------------------------- +.............................................. You've got Git, so check out our top-level repository. Type this command anywhere besides the 'py' directory:: @@ -229,7 +235,7 @@ project's directory:: Now go on to the next step. Configure the ConceptNet database ---------------------------------- +................................. You'll probably want to run ConceptNet on a PostgreSQL database, as described in :doc:`/conceptnet/install`. If you're in the Media Lab, you'll probably want @@ -239,7 +245,7 @@ to run on *the* PostgreSQL database, so ask someone for what to put in your Finally: Test stuff ----------- +.......... Start up your ipython. Try importing ``csc.conceptnet.models`` and ``csc.divisi2``. Run some of the code in the "Examples" sections. If it works, you're all set. diff --git a/docs/divisi2 b/docs/divisi2 new file mode 120000 index 0000000..aa1a67a --- /dev/null +++ b/docs/divisi2 @@ -0,0 +1 @@ +../divisi2/doc/ \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 0394ede..cb6425f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,7 @@ Commonsense Computing Documentation install conceptnet/index divisi/index + divisi2/index developers/index luminoso/index