Merge branch 'master' into move-file-validations-out-of-the-config-module

Author: stsewd

.github/FUNDING.yml

@@ -0,0 +1 @@
+custom: https://readthedocs.org/sustainability/

.gitignore

@@ -28,6 +28,7 @@ logs/*
 media/dash
 media/epub
 media/export
+media/html
 media/htmlzip
 media/json
 media/man

common

@@ -14,15 +14,7 @@ Authentication and authorization
 --------------------------------
 
 Requests to the Read the Docs public API are for public and private information.
-Some listing endpoints and some detailed ones are allowed to access without being authenticated.
-Although, all endpoints that perform non-readonly operations, require authentication.
-
-
-No authentication
-~~~~~~~~~~~~~~~~~
-
-Some endpoints on read-only requests won't require any kind of authentication.
-Most of them are detailed information of specific listings for a particular object.
+All endpoints require authentication.
 
 
 Token
@@ -35,6 +27,10 @@ and have the same permissions that the user itself.
 Session
 ~~~~~~~
 
+.. warning::
+
+   Authentication via session is not enabled yet.
+
 Session authentication is allowed on very specific endpoints,
 to allow hitting the API when reading documentation.
 
@@ -77,13 +73,16 @@ Projects list
     :>json string previous: URI for previous set of projects.
     :>json array results: array of ``project`` objects.
 
-    :query string privacy_level: one of ``public``, ``private``, ``protected``.
+    :query string name: name of the project.
+    :query string name__contains: part of the name of the project.
+    :query string slug: slug of the project.
+    :query string slug__contains: part of the slug of the project.
     :query string language: language code as ``en``, ``es``, ``ru``, etc.
+    :query string privacy_level: one of ``public``, ``private``, ``protected``.
     :query string programming_language: programming language code as ``py``, ``js``, etc.
-    :query string repository_url: URL of the repository.
     :query string repository_type: one of ``git``, ``hg``, ``bzr``, ``svn``.
 
-    :requestheader Authorization: required token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
 
 Project details
@@ -97,7 +96,7 @@ Project details
 
     .. sourcecode:: bash
 
-        $ curl https://readthedocs.org/api/v3/projects/pip/
+        $ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/
 
     **Example response**:
 
@@ -168,9 +167,7 @@ Project details
 
     .. TODO: complete the returned data docs once agreed on this.
 
-    :query boolean inactive_versions: whether or not include inactive versions.
-
-    :requestheader Authorization: optional token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
     :statuscode 200: Success
     :statuscode 404: There is no ``Project`` with this slug
@@ -199,7 +196,7 @@ Versions listing
 
     .. sourcecode:: bash
 
-        $ curl https://readthedocs.org/api/v3/projects/pip/versions/
+        $ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/versions/
 
     **Example response**:
 
@@ -225,7 +222,7 @@ Versions listing
     :query boolean active: whether return active versions only
     :query boolean built: whether return only built version
 
-    :requestheader Authorization: optional token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
 
 Version detail
@@ -239,7 +236,7 @@ Version detail
 
     .. sourcecode:: bash
 
-        $ curl https://readthedocs.org/api/v3/projects/pip/versions/stable/
+        $ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/versions/stable/
 
     **Example response**:
 
@@ -287,7 +284,7 @@ Version detail
     :>json string last_build: Build object representing the last build of this version
     :>json array downloads: URLs to downloads of this version's documentation
 
-    :requestheader Authorization: optional token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
     :statuscode 200: Success
     :statuscode 404: There is no ``Version`` with this slug for this project
@@ -309,11 +306,7 @@ Version edit
             "privacy_level": "public"
         }
 
-    **Example response**:
-
-    `See Version details <#version-detail>`_
-
-    :requestheader Authorization: required token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
     :statuscode 204: Edited sucessfully
     :statuscode 400: Some field is invalid
@@ -344,7 +337,7 @@ Build details
 
     .. sourcecode:: bash
 
-        $ curl https://readthedocs.org/api/v3/projects/pip/builds/8592686/?include_config=true
+        $ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/builds/8592686/?expand=config
 
     **Example response**:
 
@@ -422,29 +415,12 @@ Build details
 
     :query boolean include_config: whether or not include the configs used for this build. Default is ``false``
 
-    :requestheader Authorization: optional token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
     :statuscode 200: Success
     :statuscode 404: There is no ``Build`` with this ID
 
 
-.. http:get:: /api/v3/projects/(str:project_slug)/builds/latest/
-
-    Retrieve details for latest build on this project.
-
-    **Example request**:
-
-    .. sourcecode:: bash
-
-        $ curl https://readthedocs.org/api/v3/projects/pip/builds/latest/
-
-    **Example response**:
-
-    `See Build details <#build-details>`_
-
-    :requestheader Authorization: optional token to authenticate.
-
-
 Builds listing
 ++++++++++++++
 
@@ -472,102 +448,28 @@ Builds listing
     :query string commit: commit hash to filter the builds returned by commit
     :query boolean running: whether or not to filter the builds returned by currently building
 
-    :requestheader Authorization: optional token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
 
 Build triggering
 ++++++++++++++++
 
 
-.. http:post:: /api/v3/projects/(string:project_slug)/builds/
-
-    Trigger a new build for this project.
-
-    **Example request**:
-
-    .. sourcecode:: json
+.. http:post:: /api/v3/projects/(string:project_slug)/versions/(string:version_slug)/builds/
 
-        {
-            "version": "latest",
-        }
+    Trigger a new build for the ``version_slug`` version of this project.
 
     **Example response**:
 
     `See Build details <#build-details>`_
 
-    :requestheader Authorization: required token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
-    :statuscode 201: Created sucessfully
+    :statuscode 202: Accepted
     :statuscode 400: Some field is invalid
     :statuscode 401: Not valid permissions
 
 
-Build commands listing
-++++++++++++++++++++++
-
-.. http:get:: /api/v3/projects/(str:project_slug)/builds/(int:build_id)/commands/
-
-    Retrieve build command list of a single build.
-
-    **Example request**:
-
-    .. sourcecode:: bash
-
-        $ curl https://readthedocs.org/api/v3/projects/pip/builds/719263915/commands/
-
-    **Example response**:
-
-    .. sourcecode:: json
-
-        {
-            "count": 15,
-            "next": "/api/v3/projects/pip/builds/719263915/commands/?limit=10&offset=10",
-            "previous": null,
-            "results": ["BUILDCOMMAND"]
-        }
-
-    :requestheader Authorization: optional token to authenticate.
-
-
-Build command details
-+++++++++++++++++++++
-
-.. http:get:: /api/v3/projects/(str:project_slug)/builds/(int:build_id)/commands/(int:buildcommand_id)
-
-    Retrieve build command detail.
-
-    **Example request**:
-
-    .. sourcecode:: bash
-
-        $ curl https://readthedocs.org/api/v3/projects/pip/builds/719263915/commands/9182639172/
-
-    **Example response**:
-
-    .. sourcecode:: json
-
-        {
-            "id": 9182639172,
-            "build": 719263915,
-            "project": "pip",
-            "version": "stable",
-            "created": "2018-06-19T15:15:59+00:00",
-            "finished": "2018-06-19T15:16:58+00:00",
-            "duration": 59,
-            "command": "cat docs/config.py",
-            "output": "...",
-            "exit_code": 0,
-            "links": {
-                "self": "/api/v3/projects/pip/builds/719263915/commands/9182639172/",
-                "build": "/api/v3/projects/pip/builds/719263915/",
-                "version": "/api/v3/projects/pip/versions/stable/",
-                "project": "/api/v3/projects/pip/"
-            }
-        }
-
-    :requestheader Authorization: optional token to authenticate.
-
-
 Users
 ~~~~~
 
@@ -590,36 +492,16 @@ User detail
     .. sourcecode:: json
 
         {
-            "id": 25,
             "username": "humitos",
             "created": "2008-10-23T18:12:31+00:00",
-            "last_login": "2010-10-23T18:12:31+00:00",
-            "first_name": "Manuel",
-            "last_name": "Kaufmann",
-            "email": "[email protected]",
-            "links": {
-                "self": "/api/v3/users/humitos/",
-                "projects": "/api/v3/projects/?user=humitos"
-            }
+            "last_login": "2010-10-23T18:12:31+00:00"
         }
 
-    .. TODO: considering that ``/api/v3/projects/`` will return only
-       the projects for the authenticated user, the ``projects`` link
-       here won't work.
-
-       On the other hand, ``/api/v3/projects/all/?user=humitos`` can't
-       be used because we will be mixing ``all`` as project slug with
-       our endpoint URL.
-
-    :>json integer id: ID for the user on the database.
     :>json string username: username for the user.
     :>json string created: date and time when the user was created.
     :>json string last_login: date and time for last time this user was logged in.
-    :>json string first_name: first name of the user.
-    :>json string last_name: last name of the user.
-    :>json string email: email of the user.
 
-    :requestheader Authorization: required token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
 
 User listing
@@ -652,7 +534,7 @@ User listing
     :>json string previous: URI for previous set of users.
     :>json array results: array of ``user`` objects.
 
-    :requestheader Authorization: optional token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
 
 Subprojects
@@ -688,7 +570,7 @@ Subprojects listing
     :>json string previous: URI for previous set of projects.
     :>json array results: array of ``project`` objects.
 
-    :requestheader Authorization: required token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
 
 Translations
@@ -724,4 +606,4 @@ Translations listing
     :>json string previous: URI for previous set of projects.
     :>json array results: array of ``project`` objects.
 
-    :requestheader Authorization: required token to authenticate.
+    :requestheader Authorization: token to authenticate.

docs/api/v3.rst

@@ -1,19 +1,35 @@
 Read the Docs Commercial Features
 ---------------------------------
 
-.. note:: These features are for our new commercial offering, `readthedocs.com`_.
+Read the Docs has a community solution for open source projects on `readthedocs.org`_
+and we offer commercial documentation building and hosting on `readthedocs.com`_.
+Features in this section are specific to our commercial offering.
 
+Private repositories and private documentation
+    The largest difference between the community solution and our commercial offering
+    is the ability to connect to private repositories,
+    to restrict documentation access to certain users,
+    or to share private documentation via private hyperlinks.
 
-All of the other features outlined in these docs work on both sites.
-Things inside this section are specific to our commercial offering.
+Additional build resources
+    Do you have a complicated build process that uses large amounts
+    of CPU, memory, disk, or networking resources?
+    Our commercial offering has much higher default resources
+    that result in faster documentation build times
+    and we can increase it further for very demanding projects.
 
-The largest feature that is different is that documentation on `readthedocs.com`_ is **private**.
-If you have private code that you want documentation for,
-this is our solution.
+Priority support
+    We have a dedicated support team that responds to support requests during business hours.
+    If you need a quick turnaround, please signup for readthedocs.com.
 
+Advertising-free
+    All commercially hosted documentation is always ad-free.
+
+.. _readthedocs.org: https://readthedocs.org
 .. _readthedocs.com: https://readthedocs.com
 
 .. toctree:: 
+   :caption: Additional commercial features
 
    custom_domains
    organizations

docs/commercial/index.rst

@@ -88,6 +88,10 @@ Example:
       # Build all formats
       formats: all
 
+.. note::
+
+   PDF/epub/htmlzip output is not supported when using MkDocs  
+
 python
 ~~~~~~