Improve Documentation

BYU-PCCL · May 1, 2019 · 3dcc7c8 · 3dcc7c8
1 parent b597d41
commit 3dcc7c8
Show file tree

Hide file tree

Showing 60 changed files with 913 additions and 270 deletions.
diff --git a/.gitignore b/.gitignore
@@ -5,6 +5,7 @@
 .vscode/
 .tflogs/
 worlds/
+!docs/worlds
 build/
 env/
 venv/

diff --git a/README.md b/README.md
@@ -1,59 +1,28 @@
 # Holodeck
 
-[![Holodeck Video](https://img.youtube.com/vi/_huewiGqfrs/0.jpg)](https://www.youtube.com/watch?v=_huewiGqfrs)
+[![Holodeck Video](docs/images/sunrise_Moment.jpg)](https://www.youtube.com/watch?v=_huewiGqfrs)
 
-[![Read the docs badge](https://readthedocs.org/projects/holodeck/badge/)](https://holodeck.readthedocs.io/en/develop/)
+[![Read the docs badge](https://readthedocs.org/projects/holodeck/badge/)](https://holodeck.readthedocs.io/en/develop/) ![Build Status](https://jenkins.holodeck.ml/buildStatus/icon?job=holodeck-engine%2Fdevelop)
 
 Holodeck is a high-fidelity simulator for reinforcement learning built on top of Unreal Engine 4.
 [Read the docs.](https://holodeck.readthedocs.io)
 
 ## Installation
-### Requirements
-Windows and Linux:
-* Python 3.5 or higher
-* Pip3
-* At least 3gb storage
-
-Linux:
-* OpenGL version 3 or higher
-
-### Pip Installation
-To install the python bindings, simply run
-`pip3 install holodeck`
-
-Note: for some versions of pip you may see a warning, but holodeck will be installed anyway.
-
-### Docker Installation
-For Ubuntu 16.04 and Cuda 9.0*:
-1. Install [nvidia-docker](https://github.com/nvidia/nvidia-docker/wiki/Installation-(version-2.0)) (holodeck will not be able to run without it.)
-2. Pull the docker repository and run it. (replace "*without*" with "*with*" to install with the `DefaultWorlds` package)
-3. Holodeck cannot be run with root privileges so after entering the container and before you use holodeck you must login to a normal user. The `holodeckuser` with password `"holodeck"` has been provided. This account must be used if the `with-worlds` version is selected.
-```
-docker pull pccl/holodeck:ubuntu16.04-without-worlds
-nvidia-docker run -it pccl/holodeck:ubuntu16.04-without-worlds
-```
+`pip install holodeck`
 
-*For versions other than Ubuntu 16.04 and Cuda 9.0 see [here.](https://hub.docker.com/r/pccl/holodeck/).
+(requires Python 3)
 
-### Installing Packages
-Holodeck currently contains one package, the `DefaultWorlds` package.
-Each package in turn contains a number of worlds.
-Holodeck has an internal package manager for handling packages.
-The most important commands for managing these are as follows:
-```
-import holodeck
-print(holodeck.all_packages())                 # View all packages that are available to be downloaded.
-print(holodeck.installed_packages())           # View which packages are currently installed.
-holodeck.install('DefaultWorlds')              # Installs the DefaultWorlds package.
-print(holodeck.package_info('DefaultWorlds'))  # View information on what worlds this package
-                                               # contains, and what agents are in those worlds.
-holodeck.remove('DefaultWorlds')               # Removes a package.
-```
-You only need to install packages once. You should make sure to remove them with
-`holodeck.remove(package_name)` or `holodeck.remove_all_packages()` before removing
-holodeck with pip.
+See [Installation](https://holodeck.readthedocs.io/en/latest/usage/installation.html) for complete instructions (including Docker).
+
+## Features
+ - 7+ rich worlds for training agents in, and many scenarios for those worlds
+ - Easily extend and modify training scenarios
+ - Train and control more than one agent at once
+ - Simple, OpenAI Gym-like interface
+ - High performance - simulation speeds of up to 2x real time are possible
+ - Run headless or watch your agents learn
 
-## Basic Usage
+## Usage
 Holodeck's interface is designed in the same vein as [OpenAI's Gym](https://gym.openai.com/).
 The quickest way to get acquainted with Holodeck use is to view the example.py file.
 Here is a basic walkthrough of an example that runs a Holodeck world:
@@ -148,7 +117,7 @@ Holodeck can run on headless machines with GPU accelerated rendering. This requi
 ## Citation:
 ```
 @misc{HolodeckPCCL,
-  Author = {Joshua Greaves and Max Robinson and Nick Walton and Mitchell Mortensen and Robert Pottorff and Connor Christopherson and Derek Hancock and David Wingate},
+  Author = {Joshua Greaves and Max Robinson and Nick Walton and Mitchell Mortensen and Robert Pottorff and Connor Christopherson and Derek Hancock and Jayden Milne David Wingate},
   Title = {Holodeck: A High Fidelity Simulator},
   Year = {2018},
 }

diff --git a/docs/usage/.gitignore → docs/.gitignore b/docs/usage/.gitignore → docs/.gitignore
diff --git a/docs/agents/agents.rst b/docs/agents/agents.rst
@@ -0,0 +1,23 @@
+.. _`agents`:
+
+Holodeck Agents
+===============
+
+Documentation on specific agents available in Holodeck:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Agents
+
+   android-agent
+   nav-agent
+   sphere-agent
+   turtle-agent
+   uav-agent
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Resources
+
+   sensors/sensors
diff --git a/docs/agents/android-agent.rst b/docs/agents/android-agent.rst
@@ -0,0 +1,28 @@
+.. _`android-agent`:
+
+AndroidAgent
+=============
+
+Images
+------
+
+.. image:: images/android-front.png
+   :scale: 30%
+
+.. image:: images/android-side.png
+   :scale: 30%
+
+Description
+-----------
+An android agent that can be controlled via torques supplied to its joints.
+See :class:`holodeck.agents.AndroidAgent` for more details.
+
+Control Schemes
+---------------
+.. TODO: Link to Control Scheme page
+
+- Android Torques
+
+.. TODO: Don't punt on the joint layout
+
+.. TODO: Example code
diff --git a/docs/agents/images/android-front.png b/docs/agents/images/android-front.png
diff --git a/docs/agents/images/android-side.png b/docs/agents/images/android-side.png
diff --git a/docs/agents/images/nav-agent.png b/docs/agents/images/nav-agent.png
diff --git a/docs/agents/images/sphere.png b/docs/agents/images/sphere.png
diff --git a/docs/agents/images/turtle.png b/docs/agents/images/turtle.png
diff --git a/docs/agents/images/uav-perspective.png b/docs/agents/images/uav-perspective.png
diff --git a/docs/agents/images/uav-side.png b/docs/agents/images/uav-side.png
diff --git a/docs/agents/images/uav-top.png b/docs/agents/images/uav-top.png
diff --git a/docs/agents/nav-agent.rst b/docs/agents/nav-agent.rst
@@ -0,0 +1,21 @@
+.. _`nav-agent`:
+
+NavAgent
+========
+
+Images
+------
+
+.. image:: images/nav-agent.png
+   :scale: 30%
+
+See :class:`holodeck.agents.NavAgent` for more details.
+
+Description
+-----------
+The NavAgent is not meant for training, instead it is more like target that agents can interact 
+with.
+
+It uses Unreal's AI's system to attempt to intelligently navigate towards a particular location.
+
+See :class:`holodeck.agents.NavAgent` for more details.
diff --git a/docs/agents/sensors.rst b/docs/agents/sensors.rst
@@ -0,0 +1,3 @@
+Agent Sensors and Tasks
+=======================
+
diff --git a/docs/agents/sensors/agent-sensors.rst b/docs/agents/sensors/agent-sensors.rst
@@ -0,0 +1,4 @@
+Agent Sensors
+=============
+
+.. TODO: Make lists of sensors here
diff --git a/docs/agents/sphere-agent.rst b/docs/agents/sphere-agent.rst
@@ -0,0 +1,27 @@
+.. _`sphere-agent`:
+
+SphereAgent
+===========
+
+Images
+------
+
+.. image:: images/sphere.png
+   :scale: 30%
+
+Description
+-----------
+
+A basic sphere robot that moves along a plane.
+
+See :class:`holodeck.agents.SphereAgent` for more details.
+
+Control Schemes
+---------------
+
+.. TODO: Add documentation entries for these
+
+- Action Space
+- Continuous Control Scheme
+
+.. TODO: Example code?
diff --git a/docs/agents/turtle-agent.rst b/docs/agents/turtle-agent.rst
@@ -0,0 +1,13 @@
+.. _`turtle-agent`:
+
+TurtleAgent
+===========
+
+.. image:: images/turtle.png
+   :scale: 30%
+
+Description
+-----------
+A simple turtle-bot agent.
+
+See :class:`holodeck.agents.TurtleAgent` for more details.
diff --git a/docs/agents/uav-agent.rst b/docs/agents/uav-agent.rst
@@ -0,0 +1,27 @@
+.. _`uav-agent`:
+
+UavAgent
+========
+
+Images
+------
+
+.. image:: images/uav-perspective.png
+   :scale: 20%
+
+.. image:: images/uav-top.png
+   :scale: 20%
+
+.. image:: images/uav-side.png
+   :scale: 20%
+
+Description
+-----------
+A quadcopter UAV agent. 
+
+See the :class:`holodeck.agents.UavAgent` class. 
+
+Action Spaces
+-------------
+- UAV Torques
+- UAV Roll / Pitch / Yaw targets
diff --git a/docs/changelog/changelog.rst b/docs/changelog/changelog.rst
@@ -1,3 +1,61 @@
 Changelog
 =========
 
+Holodeck 0.2.0
+--------------
+*05/02/2019*
+
+This release of Holodeck is focused on polishing existing features and allowing worlds to be customized more.
+This summer we are planning on adding much more content (worlds, agents, etc).
+
+Highlights
+~~~~~~~~~~
+- Added :ref:`Scenarios <scenarios>` to allow worlds to be more flexible and customizable
+- Documentation has been greatly expanded
+
+New Features
+~~~~~~~~~~~~
+- Added expanded teleport functionality 
+  (`#128 <https://github.com/BYU-PCCL/holodeck/issues/128>`_)
+- Add ticks per capture command for RGB Camera 
+  (`#127 <https://github.com/BYU-PCCL/holodeck/issues/127>`_)
+- Add ``__enter__`` and ``__exit__`` methods to :class:`~holodeck.environment.HolodeckEnvironment` 
+  (`#125 <https://github.com/BYU-PCCL/holodeck/issues/125>`_)
+- Add option to run headless on Linux 
+  (``should_render_viewport`` on :class:`~holodeck.environment.HolodeckEnvironment`) 
+  (`#135 <https://github.com/BYU-PCCL/holodeck/issues/135>`_)
+- Add ability to adjust rendering options 
+  (:meth:`~holodeck.environment.HolodeckEnvironment.set_render_quality`)
+  (`#136 <https://github.com/BYU-PCCL/holodeck/issues/136>`_)
+- Add environment flag that allows state to be returned as copied object 
+  instead of reference 
+  (`#151 <https://github.com/BYU-PCCL/holodeck/issues/151>`_)
+- Packages are not hard-coded on server, binaries are saved in version-specific
+  folder to prevent crosstalk 
+  (`#192 <https://github.com/BYU-PCCL/holodeck/pull/192>`_)
+- Sensors can be disabled to improve performance
+  (`#152 <https://github.com/BYU-PCCL/holodeck/pull/152>`_)
+- Add the ability to draw points, lines, arrows and boxes in the worlds
+  (`#144 <https://github.com/BYU-PCCL/holodeck/pull/144>`_)
+- Added new tasks for use with scenarios 
+
+.. TODO: Add links to tasks!
+
+Bug Fixes
+~~~~~~~~~
+- Fixed ``mmap length is greater than filesize`` error on startup 
+  (`#115 <https://github.com/BYU-PCCL/holodeck/issues/115>`_)
+- Make all unit conversions on holodeck-engine side 
+  (`#162 <https://github.com/BYU-PCCL/holodeck/issues/162>`_)
+- Fix multi-agent example (thanks bradyz!) 
+  (`#118 <https://github.com/BYU-PCCL/holodeck/issues/118>`_)
+- Make sure :meth:`~holdoeck.environment.HolodeckEnvironment.reset` called before 
+  :meth:`~holdoeck.environment.HolodeckEnvironment.tick` and
+  :meth:`~holdoeck.environment.HolodeckEnvironment.set`
+  (`#156 <https://github.com/BYU-PCCL/holodeck/issues/156>`_)
+- And many smaller bugs!
+
+Holodeck 0.1.0
+--------------
+
+Initial public release.
diff --git a/docs/conf.py b/docs/conf.py
@@ -90,7 +90,7 @@
 # Guzzle theme options (see theme.conf for more information)
 html_theme_options = {
     # Set the name of the project to appear in the sidebar
-    "project_nav_name": " Holodeck",
+    # "project_nav_name": " Holodeck",
 }
 
 # Theme options are theme-specific and customize the look and feel of a theme
@@ -102,7 +102,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

diff --git a/docs/holodeck/agents.rst b/docs/holodeck/agents.rst
@@ -1,6 +1,8 @@
 Agents
 ======
 
+For a higher level description of the agents, see :ref:`agents`.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:

diff --git a/docs/holodeck/index.rst b/docs/holodeck/index.rst
@@ -1,7 +1,4 @@
-.. Holodeck documentation master file, created by
-   sphinx-quickstart on Tue Sep 25 12:29:18 2018.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. _`holodeck-api-index`:
 
 Holodeck
 ========

diff --git a/docs/holodeck/packagemanager.rst b/docs/holodeck/packagemanager.rst
@@ -1,3 +1,5 @@
+.. _packagemanager:
+
 Package Manager
 ===============
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -7,8 +7,9 @@ Welcome to Holodeck's documentation!
    :caption: Holodeck Documentation
 
    usage/installation
-   usage/gettingstarted
-   usage/examples
+   usage/getting-started
+   packages/packages
+   agents/agents
    changelog/changelog
 
 .. toctree::
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,6 +5,7 @@ @@
     .vscode/
     .tflogs/
     worlds/
+    !docs/worlds
     build/
     env/
     venv/
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		Agent Sensors and Tasks
		=======================