Avoid using default role in documentation.

Sphinx's default role (wrapping in single backticks) is often confusing
because it doesn't render as code - which achieved using double
backticks in reStructuredText - and this differs from Markdown. In
Sphinx, the default role is rendered in the same way as wrapping with
single asterisks by default - providing italicised emphasis.

To avoid this confusion, we can override the default role to warn us
when we are using it and change existing usages to use correct markup -
double backticks where we want code, single asterisks where we want
emphasis.

CHANGELOG.rst

@@ -140,8 +140,8 @@ Breaking changes / important additions:
 - Add arbitrarily deep ListSerializer nesting `#539 <https://github.com/tfranzel/drf-spectacular/issues/539>`_
 - tighten serializer assumptions `#539 <https://github.com/tfranzel/drf-spectacular/issues/539>`_
 - fix whitespace stripping on methods
-- Rename `AutoSchema._map_field_validators()` → `.insert_field_validators()`. [Nick Pope]
-- Rename `AutoSchema._map_min_max()` → `.insert_min_max()`. [Nick Pope]
+- Rename ``AutoSchema._map_field_validators()`` → ``.insert_field_validators()``. [Nick Pope]
+- Rename ``AutoSchema._map_min_max()`` → ``.insert_min_max()``. [Nick Pope]
 - Fix detection of int64 from min/max values. [Nick Pope]
 - Fix zero handling in _map_min_max(). [Nick Pope]
 - Add support for introspection of nested validators. [Nick Pope]
@@ -157,7 +157,7 @@ Breaking changes / important additions:
 
 - Added vendor specification extensions
 - Completetly overhauled validator logic and bugfixes
-- Offline UI assets with optional ``drf-spectacular-sidecar`` package
+- Offline UI assets with optional *drf-spectacular-sidecar* package
 - several internal logic improvements and stricter assumptions
 
 
@@ -206,7 +206,7 @@ Breaking changes / important additions:
 - Severely improved path parameter detection for Django-style parameters, RE parameters, and custom converters
 - Significantly more defensive settings loading for safer project imports (less prone to import loops)
 - Improved type hint support for ``Enum`` and other native types
-- Explicit support for ``drf-nested-routers``
+- Explicit support for *drf-nested-routers*
 - A lot more small improvements
 
 
@@ -260,7 +260,7 @@ Breaking changes / important additions:
 Breaking changes / important additions:
 
 - This is a y-stream release because we added `Django checks <https://docs.djangoproject.com/en/3.2/topics/checks/>`_
-  which might emit warnings and subsequently break CI. This can be easily suppressed with Django's `SILENCED_SYSTEM_CHECKS`.
+  which might emit warnings and subsequently break CI. This can be easily suppressed with Django's ``SILENCED_SYSTEM_CHECKS``.
 - Several small fixes and features that should not have a big impact.
 
 
@@ -293,7 +293,7 @@ Breaking changes / important additions:
 
 Breaking changes / important additions:
 
-- Hotfix release that addresses a carelessly added import in `0.17.1`. In certain use-cases,
+- Hotfix release that addresses a carelessly added import in 0.17.1. In certain use-cases,
   this may have led to an import cycle inside DRF.
 
 
@@ -399,7 +399,7 @@ Breaking changes / important additions:
 0.14.0 (2021-03-09)
 -------------------
 
-- Fixed bug with `cached_property` non-Model objects not being traversed [Luke Plant]
+- Fixed bug with ``cached_property`` non-Model objects not being traversed [Luke Plant]
 - Fixed issue `#314 <https://github.com/tfranzel/drf-spectacular/issues/314>`_ - include information about view/serializer in warnings. [Luke Plant]
 - bugfix forward/reverse model traversal `#323 <https://github.com/tfranzel/drf-spectacular/issues/323>`_
 - fix nested serializer detection & smarter metadata extraction `#319 <https://github.com/tfranzel/drf-spectacular/issues/319>`_
@@ -432,13 +432,13 @@ Breaking changes / important additions:
 
 Breaking changes / important additions:
 
-- `drf-spectacular`'s custom ``DjangoFilterBackend`` removed after previous deprecation. Just use the original class again.
-- ``django-filter`` extension received a significant refactoring so your schema may have several changes, hopefully positive ones.
+- *drf-spectacular*'s custom ``DjangoFilterBackend`` removed after previous deprecation. Just use the original class again.
+- *django-filter* extension received a significant refactoring so your schema may have several changes, hopefully positive ones.
 - Added response headers feature
 - Extended ``@extend_schema(request=X)``, where ``X`` may now also be a ``Dict[content_type, serializer_etc]``
 - Updated Swagger UI version
 - Fixed several model traveral issues that may lead to PK changes in the schema
-- Added `drf-yasg's` ``swagger_fake_view``
+- Added *drf-yasg*'s ``swagger_fake_view``
 
 
 0.13.2 (2021-02-11)
@@ -491,7 +491,7 @@ Breaking changes / important additions:
 
 Breaking changes:
 
-- several small improvements that should not have a big impact. this is a y-stream release mainly due to schema changes that may occur with ``django-filter``.
+- several small improvements that should not have a big impact. this is a y-stream release mainly due to schema changes that may occur with *django-filter*.
 
 
 0.12.0 (2020-12-19)
@@ -516,7 +516,7 @@ Breaking changes:
 
 Breaking changes:
 
-- reverted back to ``0.10.0`` Swagger UI behavior as default. Users relying on stricter CSP should use ``SpectacularSwaggerSplitView``
+- reverted back to *0.10.0* Swagger UI behavior as default. Users relying on stricter CSP should use ``SpectacularSwaggerSplitView``
 - ``tokenAuth`` slightly changed to properly model correct ``Authorization`` header
 - a lot of minor improvements that may slightly alter the schema
 
@@ -629,7 +629,7 @@ Breaking changes:
 -------------------
 
 - Temporarily pin the swagger-ui unpkg URL to 3.30.0 [Mohamed Abdulaziz]
-- Add `deepLinking` parameter [p.alekseev]
+- Add ``deepLinking`` parameter [p.alekseev]
 - added preprocessing hooks for operation list modification/filtering `#93 <https://github.com/tfranzel/drf-spectacular/issues/93>`_
 - Document effective DRF settings [John Vandenberg]
 - add format query parameter `#110 <https://github.com/tfranzel/drf-spectacular/issues/110>`_
@@ -763,7 +763,7 @@ Breaking changes:
 - explicit override for non-list serializers on ViewSet list `#49 <https://github.com/tfranzel/drf-spectacular/issues/49>`_ 
 - improve model field mapping via DRF init logic 
 - bugfix enum substitution with additional field parameters. 
-- Fix getting default parameter for `MultipleChoiceField` [p.alekseev]
+- Fix getting default parameter for ``MultipleChoiceField`` [p.alekseev]
 - bugfix model path traversal via intermediate property 
 - try to be more graceful with unknown custom model fields. `#33 <https://github.com/tfranzel/drf-spectacular/issues/33>`_ 
 
@@ -846,7 +846,7 @@ Breaking changes:
 
 Breaking changes:
 
-- removed `to_schema()` from `OpenApiParameter`. Handled in ``AutoSchema`` now.
+- removed ``to_schema()`` from ``OpenApiParameter``. Handled in ``AutoSchema`` now.
 
 0.8.8 (2020-03-21)
 ------------------

README.rst

@@ -135,16 +135,16 @@ these static files as a separate optional package. Usage is as follows:
 Release management
 ^^^^^^^^^^^^^^^^^^
 
-`drf-spectacular` deliberately stays below version ``1.x.x`` to signal that every
+*drf-spectacular* deliberately stays below version *1.x.x* to signal that every
 new version may potentially break you. For production we strongly recommend pinning the
 version and inspecting a schema diff on update.
 
 With that said, we aim to be extremely defensive w.r.t. breaking API changes. However,
 we also acknowledge the fact that even slight schema changes may break your toolchain,
 as any existing bug may somehow also be used as a feature.
 
-We define version increments with the following semantics. `y-stream` increments may contain
-potentially breaking changes to both API and schema. `z-stream` increments will never break the
+We define version increments with the following semantics. *y-stream* increments may contain
+potentially breaking changes to both API and schema. *z-stream* increments will never break the
 API and may only contain schema changes that should have a low chance of breaking you.
 
 
@@ -158,8 +158,8 @@ Generate your schema with the CLI:
     $ ./manage.py spectacular --file schema.yml
     $ docker run -p 80:8080 -e SWAGGER_JSON=/schema.yml -v ${PWD}/schema.yml:/schema.yml swaggerapi/swagger-ui
 
-If you also want to validate your schema add the `--validate` flag. Or serve your schema directly
-from your API. We also provide convenience wrappers for `swagger-ui` or `redoc`.
+If you also want to validate your schema add the ``--validate`` flag. Or serve your schema directly
+from your API. We also provide convenience wrappers for ``swagger-ui`` or ``redoc``.
 
 .. code:: python
 
@@ -175,7 +175,7 @@ from your API. We also provide convenience wrappers for `swagger-ui` or `redoc`.
 Usage
 -----
 
-`drf-spectacular` works pretty well out of the box. You might also want to set some metadata for your API.
+*drf-spectacular* works pretty well out of the box. You might also want to set some metadata for your API.
 Just create a ``SPECTACULAR_SETTINGS`` dictionary in your ``settings.py`` and override the defaults.
 Have a look at the `available settings <https://drf-spectacular.readthedocs.io/en/latest/settings.html>`_.
 

docs/blueprints.rst

@@ -4,7 +4,7 @@ Extension Blueprints
 ====================
 
 Blueprints are a collection of schema fixes for Django and REST Framework apps.
-Some libraries/apps do not play well with `drf-spectacular`'s automatic introspection.
+Some libraries/apps do not play well with *drf-spectacular*'s automatic introspection.
 With extensions you can manually provide the necessary information to generate a better schema.
 
 There is no blueprint for the app you are looking for? No problem, you can easily write extensions
@@ -39,7 +39,7 @@ djangorestframework-api-key
 ---------------------------
 
 Since `djangorestframework-api-key <https://github.com/florimondmanca/djangorestframework-api-key>`_ has
-no entry in ``authentication_classes``, `drf-spectacular` cannot pick up this library. To alleviate
+no entry in ``authentication_classes``, *drf-spectacular* cannot pick up this library. To alleviate
 this shortcoming, you can manually add the appropriate security scheme.
 
 .. note:: Usage of the ``SECURITY`` setting is discouraged, unless there are special circumstances
@@ -97,7 +97,7 @@ drf-rw-serializers
 `drf-rw-serializers`__ provides generic views, viewsets and mixins that extend the Django REST
 Framework ones adding separated serializers for read and write operations.
 
-`drf-spectacular` requires just a small ``AutoSchema`` augmentation to make it aware of
+*drf-spectacular* requires just a small ``AutoSchema`` augmentation to make it aware of
 ``drf-rw-serializers``. Remember to replace the ``AutoSchema`` in ``DEFAULT_SCHEMA_CLASS``.
 
 __ https://github.com/vintasoftware/drf-rw-serializers

docs/client_generation.rst

@@ -3,7 +3,7 @@
 Client generation
 ===============================
 
-`drf-spectacular` aims to generate the most accurate schema possible under the constraints of OpenAPI 3.0.3.
+*drf-spectacular* aims to generate the most accurate schema possible under the constraints of OpenAPI 3.0.3.
 Unfortunately, sometimes this goal conflicts with generating a good and functional client.
 
 To serve the two main use cases, i.e. documenting the API and generating clients, we opt for getting the
@@ -12,7 +12,7 @@ most accurate schema first, and then provide settings that allow to resolve pote
 .. note:: TL;DR - Simply setting ``'COMPONENT_SPLIT_REQUEST': True`` will most likely yield the best
   and most accurate client.
 
-.. note:: `drf-spectacular` generates warnings where it recognizes potential problems. Some warnings
+.. note:: *drf-spectacular* generates warnings where it recognizes potential problems. Some warnings
   are important to having a correct client. Fixing all warning is highly recommended.
 
 .. note:: For generating clients with CI, we highly recommend using

docs/conf.py

@@ -17,7 +17,7 @@
 
 settings.configure(USE_I18N=False, USE_L10N=False)
 
-sys.path.insert(0, os.path.abspath('../'))
+sys.path[:0] = [os.path.abspath('../'), os.path.abspath('./')]
 
 # -- Project information -----------------------------------------------------
 
@@ -33,6 +33,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'extensions',
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
 ]
@@ -45,6 +46,8 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+default_role = 'default-role-error'
+
 nitpicky = True
 
 nitpick_ignore_regex = [

docs/customization.rst

@@ -7,15 +7,15 @@ You are not satisfied with your generated schema? Follow these steps in order to
 schema closer to your API.
 
 .. note:: The warnings emitted by ``./manage.py spectacular --file schema.yaml --validate``
-  are intended as an indicator to where `drf-spectacular` discovered issues.
+  are intended as an indicator to where *drf-spectacular* discovered issues.
   Sane fallbacks are used wherever possible and some warnings might not even be relevant to you.
   The remaining issues can be solved with the following steps.
 
 Step 1: ``queryset`` and ``serializer_class``
 ---------------------------------------------
 Introspection heavily relies on those two attributes. ``get_serializer_class()``
 and ``get_serializer()`` are also used if available. You can also set those
-on ``APIView``. Even though this is not supported by DRF, `drf-spectacular` will pick
+on ``APIView``. Even though this is not supported by DRF, *drf-spectacular* will pick
 them up and use them.
 
 
@@ -78,7 +78,7 @@ discovered in the introspection.
 
 Step 3: :py:class:`@extend_schema_field <drf_spectacular.utils.extend_schema_field>` and type hints
 ---------------------------------------------------------------------------------------------------
-A custom ``SerializerField`` might not get picked up properly. You can inform `drf-spectacular`
+A custom ``SerializerField`` might not get picked up properly. You can inform *drf-spectacular*
 on what is to be expected with the :py:func:`@extend_schema_field <drf_spectacular.utils.extend_schema_field>`
 decorator. It takes either basic types or a ``Serializer`` as argument. In case of basic types
 (e.g. ``str``, ``int``, etc.) a type hint is already sufficient.
@@ -144,7 +144,7 @@ Usually, you cannot easily decorate or modify ``View``, ``Serializer`` or ``Fiel
 Extensions provide a way to hook into the introspection without actually touching the library.
 
 All extensions work on the same principle. You provide a ``target_class`` (import path
-string or actual class) and then state what `drf-spectcular` should use instead of what
+string or actual class) and then state what *drf-spectcular* should use instead of what
 it would normally discover.
 
 .. note:: The extensions register themselves automatically. Just be sure that the Python
@@ -161,7 +161,7 @@ it would normally discover.
 
 Replace views with :py:class:`OpenApiViewExtension <drf_spectacular.extensions.OpenApiViewExtension>`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Many libraries use ``@api_view`` or ``APIView`` instead of `ViewSet` or `GenericAPIView`.
+Many libraries use ``@api_view`` or ``APIView`` instead of ``ViewSet`` or ``GenericAPIView``.
 In those cases, introspection has very little to work with. The purpose of this extension
 is to augment or switch out the encountered view (only for schema generation). Simply extending
 the discovered class ``class Fixed(self.target_class)`` with a ``queryset`` or
@@ -205,7 +205,7 @@ A simple custom HTTP header based authentication could be achieved like this:
 
 Declare field output with :py:class:`OpenApiSerializerFieldExtension <drf_spectacular.extensions.OpenApiSerializerFieldExtension>`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This is mainly targeted to custom `SerializerField`'s that are within library code. This extension
+This is mainly targeted to custom ``SerializerField``'s that are within library code. This extension
 is functionally equivalent to :py:func:`@extend_schema_field <drf_spectacular.utils.extend_schema_field>`
 
 .. code-block:: python
@@ -220,17 +220,17 @@ is functionally equivalent to :py:func:`@extend_schema_field <drf_spectacular.ut
 
 Declare serializer magic with :py:class:`OpenApiSerializerExtension <drf_spectacular.extensions.OpenApiSerializerExtension>`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This is one of the more involved extension mechanisms. `drf-spectacular` uses those to implement
+This is one of the more involved extension mechanisms. *drf-spectacular* uses those to implement
 `polymorphic serializers <https://github.com/tfranzel/drf-spectacular/blob/master/drf_spectacular/serializers.py>`_.
 The usage of this extension is rarely necessary because most custom ``Serializer`` classes stay very
 close to the default behaviour.
 
 Declare custom/library filters with :py:class:`OpenApiFilterExtension <drf_spectacular.extensions.OpenApiFilterExtension>`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 This extension only applies to filter and pagination classes and is rarely used. Built-in support for
-`django-filters` is realized with this extension. :py:class:`OpenApiFilterExtension <drf_spectacular.extensions.OpenApiFilterExtension>`
+*django-filter* is realized with this extension. :py:class:`OpenApiFilterExtension <drf_spectacular.extensions.OpenApiFilterExtension>`
 replaces the filter's native ``get_schema_operation_parameters`` with your customized version, where you
-have full access to `drf-spectacular's` more advanced introspection features.
+have full access to *drf-spectacular*'s more advanced introspection features.
 
 
 Step 6: Postprocessing hooks