Commits

German Larrain committed 1312346

doc: updated 'index' and 'ars_links'; added many sections.

  • Participants
  • Parent commits 3fb39b1

Comments (0)

Files changed (11)

docs/sphinx/source/about.rst

+
+About ARS
+====================
+
+
+History
+----------
+
+This project was conceived, designed and started in RAL_ (Robotics and Automation Laboratory) at
+PUC_'s (Pontificia Universidad Católica de Chile) `engineering school <ES>`_.
+
+.. _RAL: http://ral.ing.puc.cl/
+.. _PUC: http://www.uc.cl/
+.. _ES: http://www.ing.puc.cl/
+

docs/sphinx/source/about_doc.rst

+
+About the documentation
+==============================
+
+
+When documenting ARS, some good practices are required. However, if you are not
+familiar with the tools or guidelines used, please do contribute by sending
+plain text and someone else will take care of including it in the proper way.
+
+Style guide
+--------------------
+
+Although not yet enforced, the
+`Python documentation style guide <http://docs.python.org/devguide/documenting.html>`_
+is the reference for writing ARS's documentation.
+
+Generation
+--------------------
+
+This documentation is generated automatically by Sphinx from
+rst (reStructuredText) files and the docstrings in the code,
+both of which are in the project's repository.
+
+For more information about Sphinx, see http://sphinx.pocoo.org/
+
+For more information about reStructuredText, see
+http://docutils.sourceforge.net/rst.html and http://sphinx.pocoo.org/rest.html
+

docs/sphinx/source/ars_links.rst

-========================================
-Project's external hyperlinks
-========================================
+
+External links
+====================
+
+..
+	========================================
+	Project's external hyperlinks
+	========================================
 
 
 -	ARS is registered at PyPI_ (Python Package Index).
 -	Its code is managed in a Mercurial repository hosted at Bitbucket_.
 -	The documentation is hosted at ReadTheDocs_ and it is generated
 	dynamically after each commit to the repository.
--	The organization under which this project was conceived and also
-	obtained funds for it, is RAL_ (Robotics Automation Laboratory) at
-	`Pontificia Universidad Católica de Chile's <http://www.uc.cl/>`_
-	`Engineering School <http://www.ing.puc.cl/>`_.
+-	RAL_ (Robotics and Automation Laboratory) is the organization under which
+	this project was conceived and also	obtained funds for it.
 -	A page in Ohloh_ tracks code commits and makes some analyses and
 	estimations of the project.
 
 Mailing list				GoogleGroup_
 PyPI						PyPI_
 SourceForge					SourceForge_
-Current wiki
 ====================		======================
 
 .. _PyPI: http://pypi.python.org/pypi/ARS/

docs/sphinx/source/contents.rst

+
+.. toctree::
+   :maxdepth: 2
+
+   about
+   ars_links
+   language_election
+   faq
+
+   python/index
+   apidoc/modules
+   dev_guide/faq
+   about_doc
+
+..
+   getting_started
+   cheatsheet
+
+..
+   python/about_python
+   python/python_resources
+   apidoc/modules
+   intro
+   tutorial/index
+   screenshots
+   videos
+   examples
+   roadmap
+
+
+..
+   whatsnew/index.rst
+   tutorial/index.rst
+   using/index.rst
+   reference/index.rst
+   library/index.rst
+   extending/index.rst
+   c-api/index.rst
+   distutils/index.rst
+   install/index.rst
+   howto/index.rst
+   faq/index.rst
+   glossary.rst
+..
+   about.rst
+   bugs.rst
+   copyright.rst
+   license.rst

docs/sphinx/source/dev_guide/faq.rst

+
+ARS developer FAQ
+====================
+
+.. seealso::
+   http://docs.python.org/devguide/faq
+
+
+Version control
+--------------------
+
+.. seealso::
+   http://docs.python.org/devguide/faq#version-control

docs/sphinx/source/faq.rst

+
+ARS Frequently Asked Questions
+==============================
+
+:Release: |version|
+:Date: |today|
+
+Well, there aren't many yet :)

docs/sphinx/source/index.rst

    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to ARS's documentation!
-===============================
+******************************
+Autonomous Robot Simulator
+******************************
 
-This is a tutorial introduction to quickly get you up and running with
-your own sphinx documentation system.  We'll cover installing sphinx,
-customizing the look and feel, using custom extensions for embedding
-plots, inheritance diagrams, syntax highlighted ipython sessions and
-more.  If you follow along the tutorial, you'll start with nothing and
-end up with this site -- it's the bootstrapping documentation tutorial
-that writes itself!
+..
+   Welcome to ARS's documentation!
+   ===============================
 
+.. warning:: This software and its documentation are currently under development so they will be subject to many changes.
 
-Contents:
+..
+   :Release: |version|
+   :Date: |today|
 
+Welcome! This is the documentation for Autonomous Robot Simulator |version|, last updated |today|.
+
+ARS is programmed in a marvelous language called Python. Of the many features
+that make it great (and have many users) is its documentation. Taking that
+into consideration, many of the sections herein were taken from the
+`official Python documentation <http://docs.python.org/>`_.
+
+
+So simple
+==========
+To create your first simulation, a few lines of code are enough! Run the
+following script ::
+
+   from ars.app import Program
+
+   class FallingBall(Program):
+
+      def create_sim_objects(self):
+         # add_sphere's arguments: radius, center, density
+         self.sim.add_sphere(0.5, (1,10,1), density=1)
+
+   if __name__ == '__main__':
+      sim_program = FallingBall()
+      sim_program.start()
+
+
+..
+   Old example
+   ====================
+
+..
+   This is a tutorial introduction to quickly get you up and running with
+   your own sphinx documentation system.  We'll cover installing sphinx,
+   customizing the look and feel, using custom extensions for embedding
+   plots, inheritance diagrams, syntax highlighted ipython sessions and
+   more.  If you follow along the tutorial, you'll start with nothing and
+   end up with this site -- it's the bootstrapping documentation tutorial
+   that writes itself!
+
+Official website
+====================
+ARS is hosted at `BitBucket <https://bitbucket.org/glarrain/ars>`_ where you
+will find the `downloads <https://bitbucket.org/glarrain/ars/downloads>`_,
+`source code <https://bitbucket.org/glarrain/ars/src>`_
+and `issue tracker <https://bitbucket.org/glarrain/ars/issues>`_ sections.
+
+Because ARS likes the Python community and the tools they use, it is
+`registered in PyPI <http://pypi.python.org/pypi/ARS/>`_
+(Python Package Index). Although useful for organizing packages, the
+main benefit is to be able to install (and upgrade) using the ``pip`` program.
+It takes just 3 words::
+
+  pip install ARS
+
+(well, you might have to prepend ``sudo`` in Linux if the current user doesn't
+have the necessary permissions. Bummer, that's 4 words now...)
+
+For support, check the
+`Google group <http://groups.google.com/group/ars-robot-simulator>`_
+and join if you want to post a message.
+
+News
+==========
+What has happened lately? (can't tell you just yet; it's still a secret!)
+
+.. https://wiki.fysik.dtu.dk/ase/#news
+
+Table of Contents
+====================
+
+..
 .. toctree::
    :maxdepth: 2
 
-   getting_started.rst
-   cheatsheet.rst
-   
-   ars_links.rst
-   apidoc/modules.rst
+.. include:: contents.rst
 
 Indices and tables
 ==================

docs/sphinx/source/language_election.rst

+
+Language election
+====================
+
+Articles
+--------------------
+
+*Why Python?* by Eric Raymond on Apr 30, 2000 in *Linux Journal*. http://www.linuxjournal.com/article/3882
+
+It was written more than 12 years ago when Python was far less powerful than
+today but, nonetheless, his opinion and first experiences with the language
+may be quite similar to what happens to some people nowadays.
+
+Language comparison
+--------------------
+
+Ohloh
+^^^^^^^^^^
+
+**What is Ohloh?**
+    Ohloh is a free, public directory of Free and Open Source Software (FOSS) and
+    the contributors who create and maintain it. Ohloh Code is a publicly available,
+    free code search site that indexes most of the projects in Ohloh.
+
+
+Programming Language Statistics
+
+* C: https://www.ohloh.net/languages/c
+* C++: https://www.ohloh.net/languages/cpp
+* Python: https://www.ohloh.net/languages/python
+* Matlab: https://www.ohloh.net/languages/matlab
+
+
+Language comparison (Monthly Commits as percent of total)
+
+* `C, C++, Matlab & Python <https://www.ohloh.net/languages/compare?commit=Update&l0=c&l1=cpp&l2=python&l3=matlab&l4=-1&measure=commits&percent=true>`_
+* `Python, C# & Java <https://www.ohloh.net/languages/compare?commit=Update&l0=python&l1=csharp&l2=java&l3=-1&l4=-1&measure=commits&percent=true>`_
+
+..
+    API: http://meta.ohloh.net/getting_started/
+    API key: ...
+    OAuth Consumer Secret: ...

docs/sphinx/source/python/about_python.rst

+
+About Python
+====================
+
+
+Basic information
+--------------------
+
+If you are curious about Python, its history, how and where it is used, check out
+the `official FAQ <http://docs.python.org/faq/index.html>`_. If unfamiliar with some terms,
+see the `glossary <http://docs.python.org/glossary.html>`_.
+
+

docs/sphinx/source/python/index.rst

+
+Python
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   about_python
+   python_resources

docs/sphinx/source/python/python_resources.rst

+
+Python resources
+==============================
+
+
+Tutorials and guides
+--------------------
+
+If you would like to get a taste of Python get
+started with `this tutorial <http://docs.python.org/tutorial/>`_
+(included in the `official documentation <http://docs.python.org/>`_) which is very straight forward and does
+not presume any previous knowledge of the language. However,
+it is recommended to have at least Python installed (see next section).
+
+Anothe way to get started from zero is the
+`Beginner’s Guide to Python <http://wiki.python.org/moin/BeginnersGuide>`_.
+
+
+Python on Windows
+--------------------
+Although Python runs on Windows with no problems, sometimes it's difficult
+to get started in this OS because of some small details that interfere with
+what whould be a smooth process on a \*Nix system.
+
+Syntax (e.g. path delimiters), permissions, end-of-line character, etc, can
+stop the user from doing what he should be doing, i.e. learning the language,
+instead of dealing with Windows annoyances (for more information on this topic,
+go to `annoyances.org <http://www.annoyances.org/>`_).
+
+That's why there is a special section on the Python documentation called
+`Python on Windows FAQ <http://docs.python.org/faq/windows.html>`_. So, if you
+are having issues with Python stuff on a Windows OS, go read that FAQ.
+
+
+Python(x,y)
+^^^^^^^^^^^^^^^^^^^^
+   `Python(x,y) <http://code.google.com/p/pythonxy/>`_
+   is a free Python distribution providing a ready-to-use scientific
+   development software for numerical computations, data analysis and data
+   visualization based on Python programming language, Qt graphical user
+   interfaces (and development framework) and Spyder interactive development
+   environment. Its purpose is to help scientific programmers used to
+   interpreted languages (such as MATLAB or IDL) or compiled languages
+   (C/C++ or Fortran) to switch to Python.
+
+It is very popular for Windows, but there is a
+`GNU/Linux version <https://code.google.com/p/pythonxy-linux/>`_ too.
+
+
+Python installation
+--------------------
+To have Python installed means you have installed a Python interpreter.
+In a UNIX-like system (e.g. GNU-Linux, Mac OS, etc) you probably won't need to
+because it is often included in the base installation. On Microsoft Windows,
+however, it is not so you won't have it unless it was a dependency for some
+software (e.g. GIMP).
+Curious about that? Go read `Why is Python Installed on my Computer? FAQ <http://docs.python.org/faq/installed.html#why-is-python-installed-on-my-machine>`_
+
+
+Online interpreters/shells
+------------------------------
+
+If you can't or don't want to install Python, you can resort to online
+interpreters made available by some generous or commercial efforts. Here are free alternatives:
+
+* The `repl.it project <http://repl.it/>`_ is an attempt to create an online environment for
+  interactively exploring programming languages. It provides a fully-featured
+  terminal emulator and code editor, powered by interpreter engines for more than
+  15 languages.
+  All our interpreters are written in (or compiled to) JavaScript, and run
+  completely on the user's device, regardless or whether it's a desktop, laptop or
+  phone.
+* `PythonAnywhere <http://www.pythonanywhere.com/>`_ is a Python development and
+  hosting environment that displays in
+  your web browser and runs on our servers. They're already set up with everything
+  you need. It's easy to use, fast, and powerful. There's even a useful free plan.
+* Try `IPython from your browser <http://www.pythonanywhere.com/try-ipython/>`_!
+  IPython is an enhanced interactive Python interpreter, offering tab completion,
+  object introspection, and much more. It's running on the right-hand side of
+  this page, so you can try it out right now.
+*  `codepad <http://codepad.org/>`_ is an online compiler/interpreter, and a simple collaboration tool.
+*  `Interactive server-side Python (2.5.2) shell for Google App Engine <http://shell.appspot.com/>`_
+* `Ideone <http://ideone.com/>`_ is something more than a pastebin; it's an online compiler and debugging tool which allows
+  to compile and run code online in more than 40 programming languages.
+* http://mathcs.holycross.edu/~kwalsh/python/
+* http://people.csail.mit.edu/pgbovine/python/
+* http://www.trypython.org/ requires Microsoft Silverlight :(
+
+
+Other
+--------------------
+
+
+http://www.rackspace.com/knowledge_center/web-resources/top-50-resources-for-programming-web-applications-with-python
+  Python is a general purpose, object-oriented programming language that has
+  achieved popularity because of its readability and clear syntax. Guido van
+  Rossum created Python in late 1980s. It is a ‘high level’ scripting language
+  used by most programmers for its simplicity of use. Python can be written once
+  and run on any computer. It’s a ‘multi paradigm programming language’
+  compatible with many other programming languages such as .NET, CORBA, Java, Perl.
+
+
+`Dave Kuhlman's page <http://cutter.rexx.com/~dkuhlman/>`_.
+Open Source software projects by Dave Kuhlman.
+
+  These projects are implemented in or for Python. These projects center around XML,
+  parsing XML, etc. They provide tools for building data mapping and Web services.
+  Keywords are: python, xml, editor, text processing, python training.