Added setup information, API documentation

README.md

@@ -1,19 +1,3 @@
 # Youniversity
 
-[![Docs](https://readthedocs.org/projects/social/badge/?version=latest)](https://social.readthedocs.org)
-
-## Setup
-
-1. Setup virtual environment: `virtualenv venv; source venv/bin/activate`
-2. Setup requirements: `pip install -r requirements.txt`
-3. Sync database: `python manage.py migrate`
-4. Add user: `python manage.py createsuperuser`
-5. Run webserver: `python manage.py runserver`
-6. Visit the admin page at `http://localhost:8000/admin/`
-7. Fix the first site name from example.com to localhost:8000
-8. Add a new social app, using your Facebook app ID and secret
-
-## Development
-
-- Run webserver: `python manage.py runserver`
-- Enter the front page at http://localhost:8000/static/index.html
+[![Docs](https://readthedocs.org/projects/social/badge/?version=latest)](https://social.readthedocs.org)

authapi/views.py

@@ -7,7 +7,7 @@ class UserViewSet(APIView):
 	This API is used to check whether the current user is logged in
 	and to retrieve information about the user.
 
-	It could be accessed at /api/auth/check
+	It could be accessed at :http:get:`/api/auth/check`
 
 	"""
 	def get(self, request):

docs/User.rst

@@ -0,0 +1,28 @@
+User package
+============
+
+.. automodule:: User
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+User.models module
+------------------
+
+.. automodule:: User.models
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+User.views module
+-----------------
+
+.. automodule:: User.views
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+

docs/api/auth.rst

@@ -0,0 +1,45 @@
+auth
+=================
+
+This endpoint is handled by :py:mod:`authapi.views`
+
+.. http:get:: /api/auth/check
+   :synopsis: Validate current user session
+
+   This API is used to check whether the current user is logged in
+   and to retrieve information about the user.
+
+   This endpoint is handled by :py:func:`authapi.views.UserViewSet.get`
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /api/auth/check HTTP/1.1
+      Host: social.whs.in.th
+      Accept: application/json, text/javascript
+      Cookie: sessionid=.....
+
+   **Example response when logged in**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+      X-Frame-Options: SAMEORIGIN
+      Allow: GET, HEAD, OPTIONS
+
+      "whs"
+
+   **Example response when not logged in**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 403 FORBIDDEN
+      Content-Type: application/json
+      X-Frame-Options: SAMEORIGIN
+      Allow: GET, HEAD, OPTIONS
+
+      ""
+
+   :statuscode 403: User is not logged in

docs/api/index.rst

@@ -0,0 +1,9 @@
+API Documentation
+========================
+
+The API root is at ``/api``
+
+.. toctree::
+   :maxdepth: 4
+
+   auth

docs/conf.py

@@ -35,6 +35,7 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
+    'sphinxcontrib.httpdomain',
     'sphinx.ext.napoleon'
 ]
 

docs/index.rst

@@ -4,5 +4,14 @@ Youniversity
 .. toctree::
    :maxdepth: 4
 
-   authapi
-   newsfeed
+   setup
+   api/index
+   modules
+
+Indices and tables
+-------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+* `HTTP Routing Table <http-routingtable.html>`_

docs/modules.rst

@@ -0,0 +1,9 @@
+Modules Index
+=============
+
+.. toctree::
+   :maxdepth: 4
+
+   User
+   authapi
+   newsfeed

docs/newsfeed.rst

@@ -9,14 +9,6 @@ newsfeed package
 Submodules
 ----------
 
-newsfeed.admin module
----------------------
-
-.. automodule:: newsfeed.admin
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 newsfeed.models module
 ----------------------
 
@@ -25,14 +17,6 @@ newsfeed.models module
     :undoc-members:
     :show-inheritance:
 
-newsfeed.tests module
----------------------
-
-.. automodule:: newsfeed.tests
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 newsfeed.views module
 ---------------------
 

docs/routingtable.py

@@ -0,0 +1,11 @@
+from sphinx.domains.std import StandardDomain
+
+
+def setup(app):
+    StandardDomain.initial_data['labels']['routingtable'] = (
+        'http-routingtable',
+        '',
+        'HTTP Routing Table')
+    StandardDomain.initial_data['anonlabels']['routingtable'] = (
+        'http-routingtable',
+        '')

docs/setup.rst

@@ -0,0 +1,45 @@
+Getting started
+====================
+
+1. Setup virtual environment::
+   
+      virtualenv venv
+      source venv/bin/activate
+
+2. Setup requirements::
+
+      pip install -r requirements.txt
+
+3. Sync database::
+
+      python manage.py migrate
+
+4. Add user::
+   
+      python manage.py createsuperuser
+
+5. Run webserver::
+
+      python manage.py runserver
+
+Starting the web server
+-------------------------
+
+1. Run webserver::
+
+      python manage.py runserver
+
+2. Enter the front page at `http://localhost:8000/static/index.html <http://localhost:8000/static/index.html>`_
+
+
+Configure Facebook login
+-----------------------------
+
+1. Enter Django administration page at `http://localhost:8000/admin/ <http://localhost:8000/admin/>`_
+2. Click *Sites* then fix the first site name from ``example.com`` to ``localhost:8000``
+3. Go back to front page and click *Social applications*
+4. Add new social application. Enter the following information:
+
+   * Name: Facebook
+   * Client ID, Secret Key: As given by Facebook (`Register a new Facebook application <https://developers.facebook.com/apps/>`_)
+   * Sites: Add ``localhost:8000`` to the list

docs/update.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 cd `dirname $0`/..
-sphinx-apidoc -f -M -H Youniversity -o docs . \
-	*/urls.py */migrations manage.py social ui
-mv docs/modules.rst docs/index.rst
+sphinx-apidoc -f -M -H "Modules Index" -o docs . \
+	*/urls.py */migrations */tests* */admin* \
+	manage.py social ui docs
 sphinx-build -b html docs docs/_build

requirements.txt

@@ -23,5 +23,6 @@ snowballstemmer==1.2.0
 Sphinx==1.3.1
 sphinx-autobuild==0.5.2
 sphinx-rtd-theme==0.1.9
+sphinxcontrib-httpdomain==1.4.0
 tornado==4.2.1
 watchdog==0.8.3