From d1ac18454612311576447c0224b789d0219fadb8 Mon Sep 17 00:00:00 2001 From: Manatsawin Hanmongkolchai Date: Tue, 29 Sep 2015 09:43:47 +0700 Subject: [PATCH] Added setup information, API documentation --- README.md | 18 +----------------- authapi/views.py | 2 +- docs/User.rst | 28 +++++++++++++++++++++++++++ docs/api/auth.rst | 45 ++++++++++++++++++++++++++++++++++++++++++++ docs/api/index.rst | 9 +++++++++ docs/conf.py | 1 + docs/index.rst | 13 +++++++++++-- docs/modules.rst | 9 +++++++++ docs/newsfeed.rst | 16 ---------------- docs/routingtable.py | 11 +++++++++++ docs/setup.rst | 45 ++++++++++++++++++++++++++++++++++++++++++++ docs/update.sh | 6 +++--- requirements.txt | 1 + 13 files changed, 165 insertions(+), 39 deletions(-) create mode 100644 docs/User.rst create mode 100644 docs/api/auth.rst create mode 100644 docs/api/index.rst create mode 100644 docs/modules.rst create mode 100644 docs/routingtable.py create mode 100644 docs/setup.rst diff --git a/README.md b/README.md index 0cd1d99..d670237 100644 --- a/README.md +++ b/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 \ No newline at end of file +[![Docs](https://readthedocs.org/projects/social/badge/?version=latest)](https://social.readthedocs.org) \ No newline at end of file diff --git a/authapi/views.py b/authapi/views.py index 8bcd093..b938266 100644 --- a/authapi/views.py +++ b/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): diff --git a/docs/User.rst b/docs/User.rst new file mode 100644 index 0000000..7126ad5 --- /dev/null +++ b/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: + + diff --git a/docs/api/auth.rst b/docs/api/auth.rst new file mode 100644 index 0000000..8574ee6 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 0000000..4427c3d --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,9 @@ +API Documentation +======================== + +The API root is at ``/api`` + +.. toctree:: + :maxdepth: 4 + + auth diff --git a/docs/conf.py b/docs/conf.py index 5e3a4cd..c552e81 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -35,6 +35,7 @@ 'sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', + 'sphinxcontrib.httpdomain', 'sphinx.ext.napoleon' ] diff --git a/docs/index.rst b/docs/index.rst index 528429e..e92a0d9 100644 --- a/docs/index.rst +++ b/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 `_ diff --git a/docs/modules.rst b/docs/modules.rst new file mode 100644 index 0000000..0f60fcb --- /dev/null +++ b/docs/modules.rst @@ -0,0 +1,9 @@ +Modules Index +============= + +.. toctree:: + :maxdepth: 4 + + User + authapi + newsfeed diff --git a/docs/newsfeed.rst b/docs/newsfeed.rst index 23f833b..5f383d0 100644 --- a/docs/newsfeed.rst +++ b/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 --------------------- diff --git a/docs/routingtable.py b/docs/routingtable.py new file mode 100644 index 0000000..1518202 --- /dev/null +++ b/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', + '') \ No newline at end of file diff --git a/docs/setup.rst b/docs/setup.rst new file mode 100644 index 0000000..b1e5ab5 --- /dev/null +++ b/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 `_ + + +Configure Facebook login +----------------------------- + +1. Enter Django administration page at `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 `_) + * Sites: Add ``localhost:8000`` to the list \ No newline at end of file diff --git a/docs/update.sh b/docs/update.sh index fa9a821..736896b 100755 --- a/docs/update.sh +++ b/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 \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 5470e9d..03fbfa0 100644 --- a/requirements.txt +++ b/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