Make the readme a real file, not a symlink

The readme should render correctly when processed by rst2html, displayed on
GitHub, or read as a standalone file. In contrast, the main body of
documentation must be compiled before being read. Split the readme and main body
of documentation apart.

Add a table of contents to `docs/index.rst`.

Fix a random error in `robottelo/orm.py`.

README.rst

@@ -0,0 +1,24 @@
+Robottelo
+=========
+
+`Robottelo`_ is a test suite which exercises `The Foreman`_. All tests are
+automated, suited for use in a continuous integration environment, and `data
+driven`_. There are three types of tests:
+
+* UI tests, which rely on Selenium's `WebDriver`_.
+* CLI tests, which rely on `Paramiko`_.
+* API tests, which rely on `Requests`_.
+
+The `full documentation
+<http://robottelo.readthedocs.org/en/latest/index.html>`_ is available on
+ReadTheDocs. It can also be generated locally::
+
+    pip install -r requirements-optional.txt
+    make docs
+
+.. _data driven: http://en.wikipedia.org/wiki/Data-driven_testing
+.. _Paramiko: http://www.paramiko.org/
+.. _Requests: http://docs.python-requests.org/en/latest/
+.. _Robottelo: https://github.com/SatelliteQE/robottelo
+.. _The Foreman: http://theforeman.org/
+.. _WebDriver: http://docs.seleniumhq.org/projects/webdriver/

docs/index.rst

@@ -9,15 +9,13 @@ driven`_. There are three types of tests:
 * CLI tests, which rely on `Paramiko`_.
 * API tests, which rely on `Requests`_.
 
+.. contents::
+
 Quickstart
 ==========
 
-The following is only a brief setup guide for `Robottelo`_. More extensive
-documentation `is available <http://robottelo.readthedocs.org/en/latest/>`_ at
-Read the Docs.
-
-Requirements
-------------
+The following is only a brief setup guide for `Robottelo`_. The section on
+`Running the Tests`_ provides a more comprehensive guide to using Robottelo.
 
 Install Python header files. The package providing these files varies per
 distribution. For example:
@@ -181,25 +179,22 @@ It is possible to run UI tests on a headless server. To do this:
 This done, UI tests no longer launch a visible web browser. Instead, UI tests
 launch a web browser within a virtual display.
 
-API Reference
-=============
-
-If you are looking for information on a specific function, class or method, this
-part of the documentation is for you. The following is an overview of the topics
-covered by the API. For more granular information, follow one of the links.
+Miscellany
+==========
 
 .. toctree::
-    :maxdepth: 2
+    :hidden:
 
+    committing
+    code_standards
+    reviewing_PRs
     api/index
 
-Miscellany
-==========
-
-Want to contribute? Before submitting code, read through the
-:doc:`committing guide </committing>` and **Robottelo** :doc:`code standards
-</code_standards>`. Ready to start reviewing pull requests? We have :doc:`a
-guide </reviewing_PRs>` for that too!
+Want to contribute? Before submitting code, read through the :doc:`committing
+guide </committing>` and **Robottelo** :doc:`code standards </code_standards>`.
+Ready to start reviewing pull requests? We have :doc:`a guide </reviewing_PRs>`
+for that too! Finally, the :doc:`API reference </api/index>` covers individual
+functions, classes, methods and modules.
 
 Bugs are listed `on GitHub <https://github.com/SatelliteQE/robottelo/issues>`_.
 If you think you've found a new issue, please do one of the following:

robottelo/orm.py

@@ -473,9 +473,9 @@ class EntityReadMixin(object):
     def read_raw(self, auth=None):
         """Get information about the current entity.
 
-        Send an HTTP GET request to :meth:`path`. Return the response. Do not
-        check the response for any errors, such as an HTTP 4XX or 5XX status
-        code.
+        Send an HTTP GET request to :meth:`Entity.path`. Return the response.
+        Do not check the response for any errors, such as an HTTP 4XX or 5XX
+        status code.
 
         :param tuple auth: A ``(username, password)`` tuple used when accessing
             the API. If ``None``, the credentials provided by
@@ -514,7 +514,7 @@ def read(self, auth=None, entity=None, attrs=None):
         All of an entity's one-to-one and one-to-many relationships are
         populated with objects of the correct type. For example, if
         ``SomeEntity.other_entity`` is a one-to-one relationship, this should
-        return ``True``::'
+        return ``True``::
 
             isinstance(
                 SomeEntity(id=N).read().other_entity,