Add doc structure + add API docs

docs/about/contributing.md

@@ -0,0 +1,8 @@
+# Contributing
+------------------
+
+Polr's source is available on GitHub, at [cydrobolt/polr](https://github.com/cydrobolt/polr)
+If you are familiar with PHP or any of the other technologies we use, your contribution would be greatly appreciated. We operate an IRC channel (`#polr`) on `irc.freenode.net:6667` for
+contributor collaboration and user support.
+
+For a list of tasks that may need help on, see [issues on GitHub](https://github.com/cydrobolt/polr/issues)

docs/about/contributors.md

@@ -0,0 +1,9 @@
+# Contributors
+----------------
+
+Polr was written and is maintained by [Chaoyi Zha](https://cydrobolt.com),
+but many other contributors have submitted code.
+Thank you to all who have submitted code, documentation, or bug reports to help make Polr
+a better project.
+
+[Contributors](https://github.com/cydrobolt/polr/graphs/contributors)

docs/about/license.md

@@ -0,0 +1,24 @@
+# License
+----------------
+
+Polr is licensed under the GPLv2+
+
+
+>Copyright (C) 2013-2015 Chaoyi Zha
+
+>This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+
+>This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+>You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+
+
+Full license text: [https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)

docs/css/base.css

@@ -0,0 +1,3 @@
+h1, h2, h3, h4, h5, h6 {
+    text-transform: none !important;
+}

docs/developer-guide/api.md

@@ -0,0 +1,139 @@
+# Polr API Documentation
+-----------------------------
+
+## API keys
+To authenticate a user to Polr, you will need to provide an API key along with
+each request to the Polr API, as a GET or POST parameter. (e.g `?key=API_KEY_HERE`)
+
+## Assigning an API key
+To assign an API key, log on from an administrator account, head over to the "Admin"
+tab, and scroll to the desired user. From there, you can open the API button dropdown to
+reset, create, or delete the user's API key. You will also be prompted to set a desired API quota. This is defined as requests per minute. You may allow unlimited requests by making the quota negative. Once the user receives an API key, they will be able to see an "API"
+tab in their user panel, which provides the information necessary to interact with the API.
+
+Alternative method: You can also assign a user an API key by editing their entry in the
+`users` database table, editing the `api_key` value to the desired API key, `api_active` to the correct value (`1` for active, `0` for inactive), and `api_quota` to the desired API quota (see above).
+
+## Actions
+Actions are passed as a segment in the URL. There are currently
+two actions implemented:
+
+- `shorten` - shortens a URL
+- `lookup` - looks up the destination of a shortened URL
+
+Actions take arguments, which are passed as GET or POST parameters.
+See [API endpoints](#api-endpoints) for more information on the actions.
+
+## Response Type
+The Polr API will reply in `plain_text` or `json`. The response type can be
+set by providing the `response_type` argument to the request. If not provided,
+the response type will default to `json`.
+
+Example `json` responses:
+```
+{
+    "action": "shorten",
+    "result": "https://PATHTOPOLR/5kq"
+}
+```
+
+```
+{
+    "action": "lookup",
+    "result": "https://google.com"
+}
+```
+
+Example `plain_text` responses:
+
+```https://PATHTOPOLR/5kq```
+
+```https://google.com```
+
+## API Endpoints
+All API calls will commence with the base URL, `/api/v2/`.
+
+### /api/v2/action/shorten
+Arguments:
+
+ - `url`: the URL to shorten (e.g `https://google.com`)
+ - `is_secret` (optional): whether the URL should be a secret URL or not. Defaults to `false`. (e.g `true` or `false`)
+ - `custom_ending` (optional): a custom ending for the short URL. If left empty, no custom ending will be assigned.
+
+
+Response: A JSON or plain text representation of the shortened URL.
+
+Example: GET `http://PATHTOPOLR/api/v2/action/shorten?key=API_KEY_HERE&url=https://google.com&custom_ending=CUSTOM_ENDING&is_secret=false`
+Response:
+```
+{
+    "action": "shorten",
+    "result": "https://PATHTOPOLR/5kq"
+}
+```
+
+Remember that the `url` argument must be URL encoded.
+
+### /api/v2/action/lookup
+The `lookup` action takes a single argument: `url_ending`. This is the URL to
+lookup. If it exists, the API will return with the destination of that URL. If
+it does not exist, the API will return with the status code 404 (Not Found).
+
+Arguments:
+
+ - `url_ending`: the link ending for the URL to look up. (e.g `5ga`)
+
+Remember that the `url` argument must be URL encoded.
+
+Example: GET `http://PATHTOPOLR/api/v2/action/lookup?key=API_KEY_HERE&ending=2`
+Response:
+```
+{
+    "action": "lookup",
+    "result": "https://google.com"
+}
+```
+
+## HTTP Error Codes
+The API will return an error code if your request was malformed or another error occured while processing your request.
+
+### HTTP 400 Bad Request
+This status code is returned in the following circumstances:
+
+- By the `shorten` endpoint
+    - In the event that the custom ending provided is already in use, a `400` error code will be returned and the message `custom ending already in use` will be returned as an error.
+- By any endpoint
+    - Your request will return a `400` if it is malformed or the contents of your arguments do not fit the required data type.
+
+### HTTP 500 Internal Server Error
+
+- By any endpoint
+    - The server has encountered an unhandled error. This is most likely due to a problem with your configuration or your server is unable to handle the request due to a bug.
+
+### HTTP 401 Unauthorized
+
+ - By any endpoint
+    - You are unauthorized to make the transaction. This is most likely due to an API token mismatch, or your API token has not be set to active.
+
+### HTTP 404 Not Found
+
+- By the `lookup` endpoint
+
+    - Returned in the circumstance that the short URL to look up was not found in the database.
+
+### HTTP 403 Forbidden
+
+- By the `shorten` endpoint
+    -  Your request was understood, but you have exceeded your quota.
+
+## Error Responses
+Example `json` error response:
+```
+{
+    "error": "custom ending already in use"
+}
+```
+
+Example `plain_text` error response:
+
+`custom ending already in use`

docs/developer-guide/libraries.md

@@ -0,0 +1,13 @@
+## Polr Libraries
+-----------------------
+
+To interact with Polr's API, you may opt to use a library or write your own integration.
+As not all languages and frameworks are currently supported by a library, it is encouraged
+that you take a look at the [API documentation](api/) to integrate Polr into your application.
+
+### Official Libraries
+- there are no official libraries for Polr 2.0 yet.
+
+### Unofficial libraries
+- there are no unofficial ibraries for Polr 2.0 yet.
+- perhaps you'd like to write one? Send a PR to add your library to this page.

docs/index.md

@@ -0,0 +1,10 @@
+![Polr Logo](logo.png)
+
+[![GitHub license](https://img.shields.io/badge/license-GPLv2%2B-blue.svg)](about/license)
+[![2.0 status](https://img.shields.io/badge/devel-2.0-red.svg)](https://github.com/cydrobolt/polr/tree/2.0-dev)
+[![GitHub release](https://img.shields.io/badge/stable-1.4.1-blue.svg)](https://github.com/cydrobolt/polr/releases)
+
+Welcome to Polr's 2.0 development branch.
+Please keep in mind 2.0 is pre-alpha, and should not be used in production.
+
+Polr is a beautiful, modern, lightweight, and minimalist open-source URL shortening application. It allows you to host your own URL shortener, to brand your URLs, and to gain control over your data. Polr is especially easy to use, and provides a modern, themable interface.

mkdocs.yml

@@ -1,7 +1,19 @@
 site_name: Polr Project
 pages:
 - Home: index.md
-- About: about.md
+- User Guide:
+    - 'Installation': 'user-guide/installation.md'
+    - 'Troubleshooting': 'user-guide/troubleshooting.md'
+- Developer Guide:
+    - 'Libraries': 'developer-guide/libraries.md'
+    - 'API Documentation': 'developer-guide/api.md'
+- About:
+    - 'License': 'about/license.md'
+    - 'Contributors': 'about/contributors.md'
+    - 'Contributing': 'about/contributing.md'
+
 theme: readthedocs
 repo_url: https://github.com/cydrobolt/polr/
 site_author: Chaoyi Zha
+extra_css:
+    - 'css/base.css'