diff --git a/docs/api/1.x/authentication.rst b/docs/api/1.x/authentication.rst index 0c624b457..e415dae9a 100644 --- a/docs/api/1.x/authentication.rst +++ b/docs/api/1.x/authentication.rst @@ -122,7 +122,7 @@ In order to know which authentication methods are supported by a *Kinto* server, } -For example, :github:`Kinto Admin ` inspects that list in order to dynamically offer several authentication options in its login form. +For example, `Kinto Admin `_ inspects that list in order to dynamically offer several authentication options in its login form. Permissions diff --git a/docs/api/1.x/openapi.rst b/docs/api/1.x/openapi.rst index 58b4d276b..4b67da2a6 100644 --- a/docs/api/1.x/openapi.rst +++ b/docs/api/1.x/openapi.rst @@ -86,7 +86,7 @@ Improving the documentation The Kinto OpenAPI description relies on `Cornice Swagger `_, -which is an extension for :rtd:`Cornice ` that extracts API +which is an extension for `Cornice `_ that extracts API information from service definitions. Cornice Swagger also needs some information that is not on the service such as *Tags*, *Possible Responses* and *operation IDs*, so you may upgrade those diff --git a/docs/api/1.x/openid.rst b/docs/api/1.x/openid.rst index 12224613b..369ce7fe3 100644 --- a/docs/api/1.x/openid.rst +++ b/docs/api/1.x/openid.rst @@ -69,7 +69,7 @@ for the configured provider ``name``. JavaScript example ------------------ -Let's go through a simple OpenID login example using the :github:`JavaScript kinto client `. +Let's go through a simple OpenID login example using the `JavaScript kinto client `_. When the user clicks a login button, it initiates the login process by redirecting the browser to the Identity Provider, which itself redirects it to the application page once successful. @@ -139,7 +139,7 @@ The ``parseToken()`` function scans the location hash to read the Identity Provi return parsed; } -Check out the :github:`full demo source code `. +Check out the `full demo source code `_. Example of login redirections @@ -160,4 +160,4 @@ When the user clicks the login button, the browser will follow a sequence of red #. Kinto redirects back to the Single Page App appending the JSON encoded ID and Access tokens to the callback URL provided at step 2 ``_ #. JavaScript code parses the location hash and reads the ID and Access tokens -The JavaScript app can now use the Access token to make authenticated calls to the Kinto server, and read the user info from the ID token fields. See :github:`demo `. +The JavaScript app can now use the Access token to make authenticated calls to the Kinto server, and read the user info from the ID token fields. See `demo `_. diff --git a/docs/community.rst b/docs/community.rst index 31cc0bbaa..517fe3ac9 100644 --- a/docs/community.rst +++ b/docs/community.rst @@ -73,7 +73,7 @@ This official documentation is maintained in `GitHub Output is written at ``docs/_build/html/index.html``. We obviously accept pull requests for this documentation, just as we accept them -for bug fixes and features! See :github:`open issues `. +for bug fixes and features! See `open issues `_. Submit feedback diff --git a/docs/concepts.rst b/docs/concepts.rst index 40ea4fd1c..5926dd528 100644 --- a/docs/concepts.rst +++ b/docs/concepts.rst @@ -110,7 +110,7 @@ See also * :term:`Kinto glossary `, for formal definitions of terms used in the documentation * :ref:`HTTP API reference documentation ` -* :blog:`Our blog post ` on permissions design in *Kinto* +* `Our blog post `_ on permissions design in *Kinto* .. _technical-architecture: @@ -121,7 +121,7 @@ Technical Architecture Every concept of bucket, group, collection or record is a REST *resource* and behaves according to the conventions of a resource. -*Kinto* relies on :rtd:`Cornice ` and :rtd:`Pyramid ` +*Kinto* relies on `Cornice `_ and `Pyramid `_ to implement the endpoints and HTTP request/response handling. .. image:: images/architecture.svg diff --git a/docs/conf.py b/docs/conf.py index 02fcc844e..32ca781c9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -128,9 +128,8 @@ # -- Options of extlinks -------------------------------------------------- extlinks = { - "github": ("https://github.com/%s/", ""), - "rtd": ("https://%s.readthedocs.io", ""), - "blog": ("https://mozilla-services.github.io/servicedenuages.fr/en/%s", ""), + # "github": ("https://github.com/%s/", ""), + # "rtd": ("https://%s.readthedocs.io", ""), } diff --git a/docs/configuration/good-practices.rst b/docs/configuration/good-practices.rst index 34f88da15..09f2198e8 100644 --- a/docs/configuration/good-practices.rst +++ b/docs/configuration/good-practices.rst @@ -264,5 +264,5 @@ The right database node is chosen based on some elements of the data query automatically. As an example, see `pgPool `_ -or :github:`pgShard ` for ways to shard a PostgreSQL +or `pgShard `_ for ways to shard a PostgreSQL database. diff --git a/docs/configuration/production.rst b/docs/configuration/production.rst index 4372515e9..8f8f72e32 100644 --- a/docs/configuration/production.rst +++ b/docs/configuration/production.rst @@ -54,7 +54,7 @@ Run a PostgreSQL server The instructions to run a local PostgreSQL database are out of scope here. -A detailed guide is :github:`available on the Kinto Wiki `. +A detailed guide is `available on the Kinto Wiki `_. Database setup @@ -153,7 +153,7 @@ The last step consists in creating the necessary tables and indices, run the ``m .. note:: Alternatively the SQL initialization files can be found in the - *Kinto* :github:`source code `. + *Kinto* `source `_. Production checklist @@ -181,7 +181,7 @@ adjustments: .. note:: For an exhaustive list of available settings and their default values, - refer to the *Kinto* :github:`source code `. + refer to the *Kinto* `source code `_. By default, nobody can read buckets list. You can change that using: @@ -339,8 +339,8 @@ run the Kinto application: Using nginx ----------- -nginx can act as a *reverse proxy* in front of :rtd:`uWSGI ` -(or any other wsgi server like `Gunicorn `_ or :rtd:`Circus `). +nginx can act as a *reverse proxy* in front of `uWSGI `_ +(or any other wsgi server like `Gunicorn `_ or `Circus `_). Download the ``uwsgi_params`` file: diff --git a/docs/configuration/settings.rst b/docs/configuration/settings.rst index e6ff57e3d..454e4c25c 100644 --- a/docs/configuration/settings.rst +++ b/docs/configuration/settings.rst @@ -376,7 +376,7 @@ Example output: JSON Logging :::::::::::: -Using a JSON logging formatter, like :github:`this one `, +Using a JSON logging formatter, like `this one `_, it is possible to output logs as JSON: .. code-block:: ini @@ -874,7 +874,7 @@ to highly complex. .. note:: - *Kinto* relies on :github:`pyramid multiauth ` to initialise authentication. + *Kinto* relies on `pyramid multiauth `_ to initialise authentication. .. seealso:: diff --git a/docs/core/permission.rst b/docs/core/permission.rst index c5b641ff3..cb8a2b7ce 100644 --- a/docs/core/permission.rst +++ b/docs/core/permission.rst @@ -117,7 +117,7 @@ To do so, specify the ``get_bound_permissions`` of the *Kinto-Core* authorizatio authz.get_bound_permissions = get_bound_permissions -In :rtd:`Kinto `, this is leveraged to implement an inheritance tree +In `Kinto `_, this is leveraged to implement an inheritance tree of permissions between nested objects. The root objects permissions still have to be specified via settings though. diff --git a/docs/core/quickstart.rst b/docs/core/quickstart.rst index 0e2622db6..0de8c8402 100644 --- a/docs/core/quickstart.rst +++ b/docs/core/quickstart.rst @@ -75,7 +75,7 @@ Like any *Pyramid* application, it can be served locally with: A *hello* view is now available at `http://localhost:6543/v0/ `_ (As well as basic endpoints like the :ref:`utilities `). -The next steps will consist in building a custom application using :rtd:`Cornice ` or +The next steps will consist in building a custom application using `Cornice `_ or **the Pyramid ecosystem**. But most likely, it will consist in **defining REST resources** using *Kinto-Core*\ 's @@ -154,7 +154,7 @@ Schema validation It is possible to validate records against a predefined schema, associated to the resource. -Currently, only :rtd:`Colander ` is supported, and it looks like this: +Currently, only `Colander `_ is supported, and it looks like this: .. code-block:: python diff --git a/docs/core/rationale.rst b/docs/core/rationale.rst index f172a6431..7f20b427f 100644 --- a/docs/core/rationale.rst +++ b/docs/core/rationale.rst @@ -90,8 +90,8 @@ Dependencies *Kinto-Core* is built on the shoulders of giants: -* :rtd:`Cornice ` for the REST helpers; -* :rtd:`Pyramid ` for the heavy HTTP stuff; +* `Cornice `_ for the REST helpers; +* `Pyramid `_ for the heavy HTTP stuff; * `SQLAlchemy `_ core, for database sessions and pooling; @@ -119,10 +119,10 @@ Built with Kinto-Core Some applications in the wild built with *Kinto-Core*: -* :rtd:`Reading List `, a service to synchronize articles between +* `Reading List `_, a service to synchronize articles between devices; -* :rtd:`Kinto `, a service to store and synchronize schema-less data. -* :rtd:`Syncto `, a service to access *Firefox Sync* using *kinto.js*. +* `Kinto `_, a service to store and synchronize schema-less data. +* `Syncto `_, a service to access *Firefox Sync* using *kinto.js*. * *Please contact us to add yours*. Any application built with *Kinto-Core*: diff --git a/docs/core/resource.rst b/docs/core/resource.rst index 81b71425e..c685b3b3c 100644 --- a/docs/core/resource.rst +++ b/docs/core/resource.rst @@ -40,8 +40,8 @@ Full example return new -See the :github:`ReadingList ` and -:github:`Kinto ` projects source code for real use cases. +See the `ReadingList `_ and +`Kinto `_ projects source code for real use cases. .. _resource-urls: @@ -92,7 +92,7 @@ HTTP methods and options ======================== In order to specify which HTTP verbs (``GET``, ``PUT``, ``PATCH``, ...) -are allowed on the resource, as well as specific custom Pyramid (or :rtd:`cornice`) +are allowed on the resource, as well as specific custom Pyramid (or `Cornice `_) view arguments, refer to the :ref:`viewset section `. diff --git a/docs/faq.rst b/docs/faq.rst index 239dd4bf1..b1a666144 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -118,7 +118,7 @@ YES™. Have a look at the ``/dev/null`` backend. ;-) Can I store files inside Kinto? ------------------------------- -Yes, using the :github:`Kinto/kinto-attachment` plugin. +Yes, using the https://github.com/Kinto/kinto-attachment plugin. I want to add business logic to Kinto! @@ -187,7 +187,7 @@ The application developer can implement custom conflict resolution strategies, using the :ref:`two versions of the object `, or the :ref:`history of actions ` of that object. -Some helpers are provided in the :github:`Kinto/kinto.js` client. The three +Some helpers are provided in the https://github.com/Kinto/kinto.js client. The three provided conflict resolution strategies are: * SERVER_WINS: local changes are overridden by remote ones ; diff --git a/docs/kinto-admin.rst b/docs/kinto-admin.rst index e4f646f62..de99b27ce 100644 --- a/docs/kinto-admin.rst +++ b/docs/kinto-admin.rst @@ -7,7 +7,7 @@ When the built-in plugin ``kinto.plugins.admin`` is enabled in configuration, a Web admin UI is available at ``/v1/admin/``. -* :github:`See dedicated repo ` +* `See dedicated repo `_ .. image:: images/screenshot-kinto-admin-1.png :align: center diff --git a/docs/overview.rst b/docs/overview.rst index 1c2da672d..cdabf9b0b 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -176,27 +176,27 @@ Key features :alt: https://thenounproject.com/search/?q=tutorial&i=24313 :width: 50px -+---------------------------------------------+---------------------------------------------+ -| |logo-javascript| | |logo-python| | -| :github:`JavaScript HTTP API client | :github:`Python HTTP API client | -| ` | ` | -+---------------------------------------------+---------------------------------------------+ -| |logo-offline| | |logo-admin| | -| Offline-first `JavaScript client | :ref:`Web Admin UI | -| `_ | ` | -+---------------------------------------------+---------------------------------------------+ -| |logo-history| | |logo-livesync| | -| :ref:`History of changes and authorship | Live :ref:`Push notifications | -| ` | ` | -+---------------------------------------------+---------------------------------------------+ -| |logo-attachment| | |logo-signature| | -| :github:`File attachments on records | :github:`Digital signature and review | -| ` | workflows ` | -+---------------------------------------------+---------------------------------------------+ -| |logo-quotas| | |logo-indexing| | -| :ref:`Storage quotas | :github:`Records indexing | -| ` | ` | -+---------------------------------------------+---------------------------------------------+ ++-----------------------------------------------+-----------------------------------------------------+ +| |logo-javascript| | |logo-python| | +| `JavaScript HTTP API client | `Python HTTP API client | +| `_ | `_ | ++-----------------------------------------------+-----------------------------------------------------+ +| |logo-offline| | |logo-admin| | +| Offline-first `JavaScript client | :ref:`Web Admin UI | +| ` | ` | ++-----------------------------------------------+-----------------------------------------------------+ +| |logo-history| | |logo-livesync| | +| :ref:`History of changes and authorship | Live :ref:`Push notifications | +| ` | ` | ++-----------------------------------------------+-----------------------------------------------------+ +| |logo-attachment| | |logo-signature| | +| `File attachments on records | `Digital signature and review | +| `_ | workflows `_ | ++-----------------------------------------------+-----------------------------------------------------+ +| |logo-quotas| | |logo-indexing| | +| :ref:`Storage quotas | `Records indexing | +| ` | `_ | ++-----------------------------------------------+-----------------------------------------------------+ **Learn from examples** diff --git a/docs/requirements.txt b/docs/requirements.txt index 43d27bdd4..4e7a39b73 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ docutils==0.16 -Sphinx==4.3.2 +Sphinx==4.4.0 sphinx_rtd_theme==1.0.0 sphinxcontrib-httpdomain==1.8.0 kinto diff --git a/docs/tutorials/app-examples.rst b/docs/tutorials/app-examples.rst index af3e4361a..96d2099e7 100644 --- a/docs/tutorials/app-examples.rst +++ b/docs/tutorials/app-examples.rst @@ -5,10 +5,10 @@ Application examples Usually, the best way to learn is to look at application examples! -An open Wiki page gives :github:`a complete list of apps in the wild `! +An open Wiki page gives `a complete list of apps in the wild `_! .. important:: We would be delighted to highlight demos, use-cases, tutorials, or applications made by the community, so don't hesitate to - :github:`add a link to yours `! + `add a link to yours `_! diff --git a/docs/tutorials/custom-id-generator.rst b/docs/tutorials/custom-id-generator.rst index e2acd64b1..f24dafa64 100644 --- a/docs/tutorials/custom-id-generator.rst +++ b/docs/tutorials/custom-id-generator.rst @@ -39,7 +39,7 @@ which can be provided as a regexp. The id generator should be random enough to avoid collisions. The random approach here serves the purpose of this tutorial, but for a production - ready implementation, have a look at :github:`dylang/shortid` for example. + ready implementation, have a look at https://github.com/dylang/shortid for example. Enable in configuration @@ -106,5 +106,5 @@ For example: Kinto.js client --------------- -The offline-first client :github:`Kinto/kinto.js` can also be configured to +The offline-first client https://github.com/Kinto/kinto.js can also be configured to generate custom ids. See `its documentation `_ for more details. diff --git a/docs/tutorials/first-steps.rst b/docs/tutorials/first-steps.rst index b75ab9243..556846f1f 100644 --- a/docs/tutorials/first-steps.rst +++ b/docs/tutorials/first-steps.rst @@ -315,7 +315,7 @@ or to resolve the conflict manually, might also be an option. .. note:: Don't run away! Remember, you will most likely use a library like - :github:`Kinto/kinto.js`, which provides nice abstractions to + https://github.com/Kinto/kinto.js, which provides nice abstractions to interact with the Kinto API. Once merged, we can send back again our modifications using the last diff --git a/docs/tutorials/install.rst b/docs/tutorials/install.rst index 5cc095f7a..20d83283e 100644 --- a/docs/tutorials/install.rst +++ b/docs/tutorials/install.rst @@ -314,7 +314,7 @@ See our :ref:`dedicated section about contributing `! Kinto Admin ----------- -In order to run a local :github:`Kinto Admin UI ` from a cloned +In order to run a local `Kinto Admin UI `_ from a cloned repo, the ``npm`` command must be available in order to build it with :: make build-kinto-admin diff --git a/docs/tutorials/notifications-websockets.rst b/docs/tutorials/notifications-websockets.rst index a316053bf..d516d7982 100644 --- a/docs/tutorials/notifications-websockets.rst +++ b/docs/tutorials/notifications-websockets.rst @@ -10,7 +10,7 @@ Currently, it relies on a plugin that sends events through WebSockets using `Pus .. note:: - Another plugin is under construction for WebPush: :github:`Kinto/kinto-webpush` + Another plugin is under construction for WebPush: https://github.com/Kinto/kinto-webpush Setup a Pusher account diff --git a/docs/tutorials/synchronisation.rst b/docs/tutorials/synchronisation.rst index 0f245d8f4..a164e60ec 100644 --- a/docs/tutorials/synchronisation.rst +++ b/docs/tutorials/synchronisation.rst @@ -211,7 +211,7 @@ Implementations =============== The **current implementation of reference** for offline-first records synchronisation is -:rtd:`Kinto.js `. +`Kinto.js `_. Before that, some other clients were implemented in the context of the