From 0404bfaee172346d234aa5309c28176e58253502 Mon Sep 17 00:00:00 2001 From: "T. Franzel" Date: Sat, 25 Sep 2021 19:49:53 +0200 Subject: [PATCH] update doc #530 --- README.rst | 12 ++++++++---- docs/drf_yasg.rst | 6 ++++++ docs/readme.rst | 2 ++ 3 files changed, 16 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 0b7a2a69..29b78812 100644 --- a/README.rst +++ b/README.rst @@ -2,9 +2,9 @@ drf-spectacular =============== -|build-status-image| |codecov| |pypi-version| |docs| +|build-status-image| |codecov| |docs| |pypi-version| |pypi-dl| -Sane and flexible `OpenAPI 3.0 `_ schema generation for `Django REST framework `_. +Sane and flexible `OpenAPI 3.0`_ schema generation for `Django REST framework`_. This project has 3 goals: 1. Extract as much schema information from DRF as possible. @@ -99,13 +99,14 @@ specify any settings, but we recommend to specify at least some metadata. # OTHER SETTINGS } +.. _sidecar: Self-contained UI installation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Certain environments have no direct access to the internet and as such are unable to retrieve Swagger UI or Redoc from CDNs. `drf-spectacular-sidecar`_ provides -the these static files as a separate optional package. Usage is as follows: +these static files as a separate optional package. Usage is as follows: .. code:: bash @@ -280,8 +281,9 @@ globally, and then simply run: $ tox +.. _Django REST framework: https://www.django-rest-framework.org/ +.. _OpenAPI 3.0: https://github.com/OAI/OpenAPI-Specification .. _tox: http://tox.readthedocs.org/en/latest/ - .. _drf-spectacular-sidecar: https://github.com/tfranzel/drf-spectacular-sidecar .. |build-status-image| image:: https://api.travis-ci.com/tfranzel/drf-spectacular.svg?branch=master @@ -292,3 +294,5 @@ globally, and then simply run: :target: https://codecov.io/gh/tfranzel/drf-spectacular .. |docs| image:: https://readthedocs.org/projects/drf-spectacular/badge/ :target: https://drf-spectacular.readthedocs.io/ +.. |pypi-dl| image:: https://img.shields.io/pypi/dm/drf-spectacular + :target: https://pypi.org/project/drf-spectacular/ \ No newline at end of file diff --git a/docs/drf_yasg.rst b/docs/drf_yasg.rst index 89f1bc9d..d06a83fa 100644 --- a/docs/drf_yasg.rst +++ b/docs/drf_yasg.rst @@ -9,6 +9,12 @@ features are being used. __ https://pypi.org/project/drf-yasg __ https://pypi.org/project/djangorestframework/ +.. note:: In contrast to `drf-yasg`, we don't package Redoc & Swagger UI but serve them via hyperliked CDNs instead. + If you want or need to serve those files yourself, you can do that with the optional + `drf-spectacular-sidecar `_. See + :ref:`installation instructions ` for further details. + + Decorators ---------- diff --git a/docs/readme.rst b/docs/readme.rst index 6b2b3ec6..7f1854e9 100644 --- a/docs/readme.rst +++ b/docs/readme.rst @@ -1 +1,3 @@ +.. _readme: + .. include:: ../README.rst \ No newline at end of file