1. German Larrain
  2. ars

Commits

German Larrain  committed 894bbfb

doc: backport from dev branch of pending changes

  • Participants
  • Parent commits f87007c
  • Branches 0.3.x

Comments (0)

Files changed (3)

File INSTALL.txt

View file
  • Ignore whitespace
+==============================
 INSTALL
+==============================
 
-(If your OS is Ubuntu, follow the instructions in "ARS installation - Ubuntu.txt", for an easier process that deals with requirements too)
+Detailed instructions for installation of ARS and its requirements are available
+in the online documentation [1].
 
-To install the software (only the "ars" package is part of the installation; docs, tests and demos are not), you need to:
+ARS itself is really easy to install :) but some of its prerequisites
+are not :( , depending on which operating system is used.
+The best option is Ubuntu, specially its 12.04 (i.e. Precise Pangolin)
+version. For that, follow the instructions in [2]. If you have another version
+of Ubuntu, steps may be the same or very similar. For other Linux distros, the
+steps regarding ``apt-get`` will probably change.
 
-1) check & install the requirements listed in README.
-2) open a command window, with the current directoy set to the project main directory
-3) execute the (included) standard python setup script (you may need administrator privileges):
-	python setup.py install
+Microsoft Windows is the OS less friendly to ARS, as well as to many other open
+source software. Nonetheless, it is very popular so we got it to run there too,
+for both XP and 7 (Vista untested). Read the corresponding section in [3].
 
-----------------------------------------
-TEST INSTALLATION
-Start the Python interpreter (with the command "python") and execute this statement:
-	import ars
+ARS has not been tested on Mac OSX but it should work fine because all the
+required software has been reported to run fine on it. ARS itself is pure Python
+and OS-agnostic thus possible issues will be related to the requirements [4].
+
+[1] http://ars-project.readthedocs.org/en/latest/installation/
+[2] http://ars-project.readthedocs.org/en/latest/installation/ubuntu_12-04.html
+[3] http://ars-project.readthedocs.org/en/latest/installation/windows.html
+[4] http://ars-project.readthedocs.org/en/latest/installation/prerequisites.html
+
+
+Installation steps
+------------------------------
+(Note: only the "ars" package is part of the installation; docs, tests and
+demos are not, although they are included in the archive file)
+
+To install ARS , you need to:
+
+1) check and install the requirements listed in the documentation.
+
+2a) If you have pip installed, you only need one command to get the package from
+the internet and install it in your system:
+	$ pip install ARS
+
+2b) If you don't have pip, open a command window, change the current directoy
+to the project main directory and execute the (included) standard Python setup
+script (you may need administrator privileges)
+	$ cd ARS-03
+	$ python setup.py install
+
+
+Test installation
+------------------------------
+Start the Python interpreter (with the command "python")
+	$ python
+and import the package
+	>>> import ars
+You may explore the contents of the package with
+	>>> help(ars)
 
 If no errors appear, you are all set.
-You may explore the contents by entering "help(ars)".
-To exit the interpreter, use "quit()".
+To exit the interpreter, use "quit()" or Ctrl+D.
 
-----------------------------------------
-RUN DEMO
-To run a demo, execute any file in the "bin" subfolder, such as:
-	python bin/FallingBall.py
-	python bin/IROS/example4_sinusoidal_terrain.py
 
-----------------------------------------
-BUILD DOCUMENTATION
+Run demos
+------------------------------
+To watch ARS in action, run any file in the "demos" subdirectory, such as:
+	$ python demos/FallingBall.py
+	$ python demos/IROS/example4_sinusoidal_terrain.py
 
-For epydoc, see ./docs/epydoc
-For sphinx, see ./docs/sphinx
+
+Build documentation
+------------------------------
+Sphinx is used to build the documentation. Most common output is HTML but a PDF
+file can be generated through Latex. A makefile is included.
+	$ docs/sphinx
+	$ make html
+	$ make latexpdf
+
+
+Note: in the past, epydoc was used. It may still possible to generate the
+documentation with it. For that, read the contents at docs/epydoc.

File README.rst

View file
  • Ignore whitespace
 `Open Dynamics Engine (ODE) <https://sourceforge.net/projects/opende/>`_
 and the `Visualization Toolkit (VTK) <http://www.vtk.org/>`_.
 
-Requirements
+Installation and Requirements
 ====================
-* Python 2.7 (developed with 2.7.3)
-  http://www.python.org/download/releases/2.7.3/
+For installation instructions and requirements, see the
+`online documentation <http://ars-project.readthedocs.org/en/latest/installation/>`_.
+
+ARS relies in these software:
+
+* Python 2.7
 * ODE (Open Dynamics Engine) 0.12 (from rev 1864 could work but is untested) with Python bindings
-  http://sourceforge.net/projects/opende/
-  http://sourceforge.net/projects/arsproject/files/ODE/
-* VTK (Visualization Toolkit) 5.8 (developed with 5.8.0 and used to be 5.2.1) with Python bindings
-  http://www.vtk.org/VTK/resources/software.html
-  https://sourceforge.net/projects/arsproject/files/VTK/
+* VTK (Visualization Toolkit) 5.8 with Python bindings
+* NumPy 1.6
 
 Documentation
 ====================

File docs/maintainers/Procedure to create and upload a release .txt

View file
  • Ignore whitespace
 0) clean working directory. The best choice is to shelve all changes.
 
 1) test that the source distribution is created appropriately (in all the archive formats)
-	python setup.py sdist --formats=gztar,zip
+	$ python setup.py sdist --formats=gztar,zip
 
 2) update version/release number and commit. Change it in
 	ars/__init__.py
 3) tag previous changeset with 'version XYZ'
 
 4) create and upload source distribution to PyPI
-	python setup.py sdist --formats=gztar,zip upload
+	$ python setup.py sdist --formats=gztar,zip upload
 
 5) test installation with 'pip'
-	sudo pip install ARS
+	$ sudo pip install ARS
+	$ python
+	>>> import ars
 
-6) hg push
+6) $ hg push
 
 7) go to https://sourceforge.net/projects/arsproject/files/ARS/ and create a folder named 'XYZ %date'
 
-8) upload to that folder
+8) upload these files to that folder
 	ARS-XYZ.tar.gz
 	ARS-XYZ.zip
 
-9) upload the same files here: https://bitbucket.org/glarrain/ars/downloads
+9) set the .zip as the default download for Windows and Mac OSX, and the .gz
+	for all the rest.
 
-10) Verify documentation builds passed here: https://readthedocs.org/builds/ars-project/
+10) upload the same files here: https://bitbucket.org/glarrain/ars/downloads
+
+11) Verify documentation builds passed here: https://readthedocs.org/builds/ars-project/