Browse files

Merge branch 'master' of github.com:Nagyman/readthedocs.org into sear…

…ch_results
  • Loading branch information...
2 parents 0e5ada2 + a2a7039 commit 447d7db15751ffba0c3490c8c5746dea27e66294 @Nagyman committed Mar 13, 2012
Showing with 501 additions and 47 deletions.
  1. +487 −41 docs/api.rst
  2. +1 −1 docs/conf.py
  3. +1 −1 pip_requirements.txt
  4. +10 −4 readthedocs/projects/tasks.py
  5. +1 −0 requirements/docs.txt
  6. +1 −0 requirements/documentation_requirements.txt
View
528 docs/api.rst
@@ -39,7 +39,7 @@ You can use `Slumber <http://slumber.in/>`_ to build basic API wrappers in pytho
print json.dumps(val, indent=4)
Example of adding a user to a project
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
::
@@ -70,69 +70,515 @@ Example of adding a user to a project
print "After users: %s" % project2_objects['users']
-API Examples
-------------
+API Endpoints
+=============
-In all of these examples, replace `pip` with your own project.
+Feel free to use cURL and python to look at formatted json examples. You can also look at them in your browser, if it handles returned json.
-Project Details
-~~~~~~~~~~~~~~~
+::
-cURL
-`````
-Feel free to use cURL and python to look at formatted json examples. You can also look at them in your browser, if it handles returned json.
+ curl http://readthedocs.org/api/v1/project/pip/?format=json | python -m json.tool
+
+Root
+----
+.. http:method:: GET /api/v1/
+
+.. http:response:: Retrieve a list of resources.
+
+ .. sourcecode:: js
+
+ {
+ "build": {
+ "list_endpoint": "/api/v1/build/",
+ "schema": "/api/v1/build/schema/"
+ },
+ "file": {
+ "list_endpoint": "/api/v1/file/",
+ "schema": "/api/v1/file/schema/"
+ },
+ "project": {
+ "list_endpoint": "/api/v1/project/",
+ "schema": "/api/v1/project/schema/"
+ },
+ "user": {
+ "list_endpoint": "/api/v1/user/",
+ "schema": "/api/v1/user/schema/"
+ },
+ "version": {
+ "list_endpoint": "/api/v1/version/",
+ "schema": "/api/v1/version/schema/"
+ }
+ }
+
+ :data string list_endpoint: API endpoint for resource.
+ :data string schema: API endpoint for schema of resource.
+
+Builds
+------
+.. http:method:: GET /api/v1/build/
+
+.. http:response:: Retrieve a list of Builds.
+
+ .. sourcecode:: js
+
+ {
+ "meta": {
+ "limit": 20,
+ "next": "/api/v1/build/?limit=20&offset=20",
+ "offset": 0,
+ "previous": null,
+ "total_count": 86684
+ },
+ "objects": [BUILDS]
+ }
+
+ :data integer limit: Number of Builds returned.
+ :data string next: URI for next set of Builds.
+ :data integer offset: Current offset used for pagination.
+ :data string previous: URI for previous set of Builds.
+ :data integer total_count: Total number of Builds.
+ :data array objects: Array of `Build`_ objects.
+
+
+Build
+-----
+.. http:method:: GET /api/v1/build/{id}/
+
+ :arg id: A Build id.
+
+.. http:response:: Retrieve a single Build.
+
+ .. sourcecode:: js
+
+ {
+ "date": "2012-03-12T19:58:29.307403",
+ "error": "SPHINX ERROR",
+ "id": "91207",
+ "output": "SPHINX OUTPUT",
+ "project": "/api/v1/project/2599/",
+ "resource_uri": "/api/v1/build/91207/",
+ "setup": "HEAD is now at cd00d00 Merge pull request #181 from Nagyman/solr_setup\n",
+ "setup_error": "",
+ "state": "finished",
+ "success": true,
+ "type": "html",
+ "version": "/api/v1/version/37405/"
+ }
+
+
+ :data string date: Date of Build.
+ :data string error: Error from Sphinx build process.
+ :data string id: Build id.
+ :data string output: Output from Sphinx build process.
+ :data string project: URI for Project of Build.
+ :data string resource_uri: URI for Build.
+ :data string setup: Setup output from Sphinx build process.
+ :data string setup_error: Setup error from Sphinx build process.
+ :data string state: "triggered", "building", or "finished"
+ :data boolean success: Was build successful?
+ :data string type: Build type ("html", "pdf", "man", or "epub")
+ :data string version: URI for Version of Build.
+
+Files
+-----
+.. http:method:: GET /api/v1/file/
+
+.. http:response:: Retrieve a list of Files.
+
+ .. sourcecode:: js
+
+ {
+ "meta": {
+ "limit": 20,
+ "next": "/api/v1/file/?limit=20&offset=20",
+ "offset": 0,
+ "previous": null,
+ "total_count": 32084
+ },
+ "objects": [FILES]
+ }
+
+
+ :data integer limit: Number of Files returned.
+ :data string next: URI for next set of Files.
+ :data integer offset: Current offset used for pagination.
+ :data string previous: URI for previous set of Files.
+ :data integer total_count: Total number of Files.
+ :data array objects: Array of `File`_ objects.
+
+File
+----
+.. http:method:: GET /api/v1/file/{id}/
+
+ :arg id: A File id.
+
+.. http:response:: Retrieve a single File.
+
+ .. sourcecode:: js
+
+ {
+ "absolute_url": "/docs/keystone/en/latest/search.html",
+ "id": "332692",
+ "name": "search.html",
+ "path": "search.html",
+ "project": {PROJECT},
+ "resource_uri": "/api/v1/file/332692/"
+ }
+
+
+ :data string absolute_url: URI for actual file (not the File object from the API.)
+ :data string id: File id.
+ :data string name: Name of File.
+ :data string path: Name of Path.
+ :data object project: A `Project`_ object for the file's project.
+ :data string resource_uri: URI for File object.
+
+Projects
+--------
+.. http:method:: GET /api/v1/project/
+
+.. http:response:: Retrieve a list of Projects.
+
+ .. sourcecode:: js
+
+ {
+ "meta": {
+ "limit": 20,
+ "next": "/api/v1/project/?limit=20&offset=20",
+ "offset": 0,
+ "previous": null,
+ "total_count": 2067
+ },
+ "objects": [PROJECTS]
+ }
+
+
+ :data integer limit: Number of Projects returned.
+ :data string next: URI for next set of Projects.
+ :data integer offset: Current offset used for pagination.
+ :data string previous: URI for previous set of Projects.
+ :data integer total_count: Total number of Projects.
+ :data array objects: Array of `Project`_ objects.
+
+
+Project
+-------
+.. http:method:: GET /api/v1/project/{id}
+
+ :arg id: A Project id.
+
+.. http:response:: Retrieve a single Project.
+
+ .. sourcecode:: js
+
+ {
+ "absolute_url": "/projects/docs/",
+ "analytics_code": "",
+ "copyright": "",
+ "crate_url": "",
+ "default_branch": "",
+ "default_version": "latest",
+ "description": "Make docs.readthedocs.org work :D",
+ "django_packages_url": "",
+ "documentation_type": "sphinx",
+ "id": "2599",
+ "modified_date": "2012-03-12T19:59:09.130773",
+ "name": "docs",
+ "project_url": "",
+ "pub_date": "2012-02-19T18:10:56.582780",
+ "repo": "git://github.com/rtfd/readthedocs.org",
+ "repo_type": "git",
+ "requirements_file": "",
+ "resource_uri": "/api/v1/project/2599/",
+ "slug": "docs",
+ "subdomain": "http://docs.readthedocs.org/",
+ "suffix": ".rst",
+ "theme": "default",
+ "use_virtualenv": false,
+ "users": [
+ "/api/v1/user/1/"
+ ],
+ "version": ""
+ }
+
+
+ :data string absolute_url: URI for project (not the Project object from the API.)
+ :data string analytics_code: Analytics tracking code.
+ :data string copyright: Copyright
+ :data string crate_url: Crate.io URI.
+ :data string default_branch: Default branch.
+ :data string default_version: Default version.
+ :data string description: Description of project.
+ :data string django_packages_url: Djangopackages.com URI.
+ :data string documentation_type: Either "sphinx" or "sphinx_html".
+ :data string id: Project id.
+ :data string modified_date: Last modified date.
+ :data string name: Project name.
+ :data string project_url: Project homepage.
+ :data string pub_date: Last published date.
+ :data string repo: URI for VCS repository.
+ :data string repo_type: Type of VCS repository.
+ :data string requirements_file: Pip requirements file for packages needed for building docs.
+ :data string resource_uri: URI for Project.
+ :data string slug: Slug.
+ :data string subdomain: Subdomain.
+ :data string suffix: File suffix of docfiles. (Usually ".rst".)
+ :data string theme: Sphinx theme.
+ :data boolean use_virtualenv: Build project in a virtualenv? (True or False)
+ :data array users: Array of readthedocs.org user URIs for administrators of Project.
+ :data string version: DEPRECATED.
+
+
+Users
+-----
+.. http:method:: GET /api/v1/user/
+
+.. http:response:: Retrieve List of Users
+
+ .. sourcecode:: js
+
+ {
+ "meta": {
+ "limit": 20,
+ "next": "/api/v1/user/?limit=20&offset=20",
+ "offset": 0,
+ "previous": null,
+ "total_count": 3200
+ },
+ "objects": [USERS]
+ }
+
+ :data integer limit: Number of Users returned.
+ :data string next: URI for next set of Users.
+ :data integer offset: Current offset used for pagination.
+ :data string previous: URI for previous set of Users.
+ :data integer total_count: Total number of Users.
+ :data array USERS: Array of `User`_ objects.
+
+
+User
+----
+.. http:method:: GET /api/v1/user/{id}/
+
+ :arg id: A User id.
+
+.. http:response:: Retrieve a single User
+
+ .. sourcecode:: js
+
+ {
+ "first_name": "",
+ "id": "1",
+ "last_login": "2010-10-28T13:38:13.022687",
+ "last_name": "",
+ "resource_uri": "/api/v1/user/1/",
+ "username": "testuser"
+ }
+
+ :data string first_name: First name.
+ :data string id: User id.
+ :data string last_login: Timestamp of last login.
+ :data string last_name: Last name.
+ :data string resource_uri: URI for this user.
+ :data string username: User name.
+
+
+Versions
+--------
+.. http:method:: GET /api/v1/version/
+
+.. http:response:: Retrieve a list of Versions.
+
+ .. sourcecode:: js
+
+ {
+ "meta": {
+ "limit": 20,
+ "next": "/api/v1/version/?limit=20&offset=20",
+ "offset": 0,
+ "previous": null,
+ "total_count": 16437
+ },
+ "objects": [VERSIONS]
+ }
+
+
+ :data integer limit: Number of Versions returned.
+ :data string next: URI for next set of Versions.
+ :data integer offset: Current offset used for pagination.
+ :data string previous: URI for previous set of Versions.
+ :data integer total_count: Total number of Versions.
+ :data array objects: Array of `Version`_ objects.
+
+
+Version
+-------
+.. http:method:: GET /api/v1/version/{id}
+
+ :arg id: A Version id.
+
+.. http:response:: Retrieve a single Version.
+
+ .. sourcecode:: js
+
+ {
+ "active": false,
+ "built": false,
+ "id": "12095",
+ "identifier": "remotes/origin/zip_importing",
+ "project": {PROJECT},
+ "resource_uri": "/api/v1/version/12095/",
+ "slug": "zip_importing",
+ "uploaded": false,
+ "verbose_name": "zip_importing"
+ }
+
+
+ :data boolean active: Are we continuing to build docs for this version?
+ :data boolean built: Have docs been built for this version?
+ :data string id: Version id.
+ :data string identifier: Identifier of Version.
+ :data object project: A `Project`_ object for the version's project.
+ :data string resource_uri: URI for Version object.
+ :data string slug: String that uniquely identifies a project
+ :data boolean uploaded: Were docs uploaded? (As opposed to being build by Read the Docs.)
+ :data string verbose_name: Usually the same as Slug.
+
+
+Filtering Examples
+------------------
+
+Find Highest Version
+~~~~~~~~~~~~~~~~~~~~
+::
-`curl http://readthedocs.org/api/v1/project/pip/?format=json |python -mjson.tool`
+ http://readthedocs.org/api/v1/version/pip/highest/?format=json
+
+.. http:method:: GET /api/v1/version/{id}/highest/
+ :arg id: A Version id.
-URL
-```
-http://readthedocs.org/api/v1/project/pip/?format=json
+.. http:response:: Retrieve highest version.
+ .. sourcecode:: js
-Build List
-~~~~~~~~~~
+ {
+ "is_highest": true,
+ "project": "Version 1.0.1 of pip (5476)",
+ "slug": [
+ "1.0.1"
+ ],
+ "url": "/docs/pip/en/1.0.1/",
+ "version": "1.0.1"
+ }
-URL
-```
-http://readthedocs.org/api/v1/build/pip/?format=json
-Version List
-~~~~~~~~~~~~
+Compare Highest Version
+~~~~~~~~~~~~~~~~~~~~~~~
-URL
-```
-http://readthedocs.org/api/v1/version/pip/?format=json
+This will allow you to compare whether a certain version is the highest version of a specific project. The below query should return a `'is_highest': false` in the returned dictionary.
+::
-Highest Version
-~~~~~~~~~~~~~~~
+ http://readthedocs.org/api/v1/version/pip/highest/0.8/?format=json
-URL
-```
-http://readthedocs.org/api/v1/version/pip/highest/?format=json
+.. http:method:: GET /api/v1/version/{id}/highest/{version}
-Compare Highest Version
-~~~~~~~~~~~~~~~~~~~~~~~
+ :arg id: A Version id.
+ :arg version: A Version number or string.
-URL
-```
-http://readthedocs.org/api/v1/version/pip/highest/0.8/?format=json
+.. http:response:: Retrieve highest version.
-This will allow you to compare whether a certain version is the highest version of a specific project. The above query should return a `'is_highest': false` in the returned dictionary.
+ .. sourcecode:: js
+
+ {
+ "is_highest": false,
+ "project": "Version 1.0.1 of pip (5476)",
+ "slug": [
+ "1.0.1"
+ ],
+ "url": "/docs/pip/en/1.0.1/",
+ "version": "1.0.1"
+ }
+
File Search
~~~~~~~~~~~
+::
-URL
-```
-http://readthedocs.org/api/v1/file/search/?format=json&q=virtualenv
-
+ http://readthedocs.org/api/v1/file/search/?format=json&q=virtualenvwrapper
+
+.. http:method:: GET /api/v1/file/search/?q={search_term}
+
+ :arg search_term: Perform search with this term.
+
+.. http:response:: Retrieve a list of `File`_ objects that contain the search term.
+
+ .. sourcecode:: js
+
+ {
+ "objects": [
+ {
+ "absolute_url": "/docs/python-guide/en/latest/scenarios/virtualenvs/index.html",
+ "id": "375539",
+ "name": "index.html",
+ "path": "scenarios/virtualenvs/index.html",
+ "project": {
+ "absolute_url": "/projects/python-guide/",
+ "analytics_code": null,
+ "copyright": "Unknown",
+ "crate_url": "",
+ "default_branch": "",
+ "default_version": "latest",
+ "description": "[WIP] Python best practices...",
+ "django_packages_url": "",
+ "documentation_type": "sphinx_htmldir",
+ "id": "530",
+ "modified_date": "2012-03-13T01:05:30.191496",
+ "name": "python-guide",
+ "project_url": "",
+ "pub_date": "2011-03-20T19:40:03.599987",
+ "repo": "git://github.com/kennethreitz/python-guide.git",
+ "repo_type": "git",
+ "requirements_file": "",
+ "resource_uri": "/api/v1/project/530/",
+ "slug": "python-guide",
+ "subdomain": "http://python-guide.readthedocs.org/",
+ "suffix": ".rst",
+ "theme": "kr",
+ "use_virtualenv": false,
+ "users": [
+ "/api/v1/user/130/"
+ ],
+ "version": ""
+ },
+ "resource_uri": "/api/v1/file/375539/",
+ "text": "...<span class=\"highlighted\">virtualenvwrapper</span>\n..."
+ },
+ ...
+ ]
+ }
Anchor Search
~~~~~~~~~~~~~
+::
+
+ http://readthedocs.org/api/v1/file/anchor/?format=json&q=virtualenv
+
+.. http:method:: GET /api/v1/file/anchor/?q={search_term}
+
+ :arg search_term: Perform search of files containing anchor text with this term.
+
+.. http:response:: Retrieve a list of absolute URIs for files that contain the search term.
+
+ .. sourcecode:: js
-URL
-```
-http://readthedocs.org/api/v1/file/anchor/?format=json&q=virtualenv
+ {
+ "objects": [
+ "http//django-fab-deploy.readthedocs.org/en/latest/...",
+ "http//dimagi-deployment-tools.readthedocs.org/en/...",
+ "http//openblock.readthedocs.org/en/latest/install/base_install.html#virtualenv",
+ ...
+ ]
+ }
View
2 docs/conf.py
@@ -6,7 +6,7 @@
from django.core.management import setup_environ
setup_environ(settings.sqlite)
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx_http_domain']
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
View
2 pip_requirements.txt
@@ -26,4 +26,4 @@ slumber
-e git+http://github.com/nathanborror/django-registration.git#egg=django-registration
-e git+https://github.com/toastdriven/django-tastypie.git#egg=tastypie
-e git+https://github.com/toastdriven/django-haystack#egg=django-haystack
-
+-e git+https://github.com/deceze/Sphinx-HTTP-domain.git#egg=sphinx-http-domain
View
14 readthedocs/projects/tasks.py
@@ -414,10 +414,16 @@ def fileify(version):
if fnmatch.fnmatch(filename, '*.html'):
dirpath = os.path.join(root.replace(path, '').lstrip('/'),
filename.lstrip('/'))
- api.file.post(dict(
- project="/api/v1/project/%s/" % project.pk,
- path=dirpath,
- name=filename))
+ if getattr(settings, 'DONT_HIT_DB', True):
+ api.file.post(dict(
+ project="/api/v1/project/%s/" % project.pk,
+ path=dirpath,
+ name=filename))
+ else:
+ ImportedFile.objects.get_or_create(
+ project=project,
+ path=dirpath,
+ name=filename)
#@periodic_task(run_every=crontab(hour="2", minute="10", day_of_week="*"))
View
1 requirements/docs.txt
@@ -0,0 +1 @@
+sphinx_http_domain
View
1 requirements/documentation_requirements.txt
@@ -0,0 +1 @@
+sphinx_http_domain

0 comments on commit 447d7db

Please sign in to comment.