Update changelog and clean up code

docs/changelog.rst

@@ -7,25 +7,27 @@ Changelog
 **1.0.5**
 *********
 
-- **FIX:** fixed a crash caused by having read-only Serializers nested by reference
-- **FIX:** removed erroneous backslashes in paths when routes are generated using Django 2
+- **FIXED:** fixed a crash caused by having read-only Serializers nested by reference
+- **FIXED:** removed erroneous backslashes in paths when routes are generated using Django 2
   `path() <https://docs.djangoproject.com/en/2.0/ref/urls/#django.urls.path>`_
-- **IMPROVEMENT:** updated ``swagger-ui`` to version 3.7.0
+- **IMPROVED:** updated ``swagger-ui`` to version 3.7.0
+- **IMPROVED:** ``FileField`` is now generated as an URL or file name in response Schemas
+  (:pr:`21`, thanks to :ghuser:`h-hirokawa`)
 
 *********
 **1.0.4**
 *********
 
-- **FIX:** fixed improper generation of YAML references
-- **FEATURE:** added ``query_serializer`` parameter to
+- **FIXED:** fixed improper generation of YAML references
+- **ADDED:** added ``query_serializer`` parameter to
   :func:`@swagger_auto_schema <.swagger_auto_schema>` (:issue:`16`, :pr:`17`)
 
 *********
 **1.0.3**
 *********
 
-- **FIX:** fixed bug that caused schema views returned from cache to fail (:issue:`14`)
-- **FIX:** disabled automatic generation of response schemas for form operations to avoid confusing errors caused by
+- **FIXED:** fixed bug that caused schema views returned from cache to fail (:issue:`14`)
+- **FIXED:** disabled automatic generation of response schemas for form operations to avoid confusing errors caused by
   attempting to shove file parameters into Schema objects
 
 *********

docs/conf.py

@@ -4,6 +4,7 @@
 # drf-yasg documentation build configuration file, created by
 # sphinx-quickstart on Sun Dec 10 15:20:34 2017.
 import os
+import re
 import sys
 
 import sphinx_rtd_theme
@@ -216,40 +217,59 @@ drf_yasg.views.SchemaView = drf_yasg.views.get_schema_view(None)
 
 # custom interpreted role for linking to GitHub issues and pull requests
 # use as :issue:`14` or :pr:`17`
-gh_issue_uri = "https://github.com/axnsan12/drf-yasg/issues/%d"
-gh_pr_uri = "https://github.com/axnsan12/drf-yasg/pull/%d"
+gh_issue_uri = "https://github.com/axnsan12/drf-yasg/issues/{}"
+gh_pr_uri = "https://github.com/axnsan12/drf-yasg/pull/{}"
+gh_user_uri = "https://github.com/{}"
+
+
+def sphinx_err(inliner, lineno, rawtext, msg):
+    msg = inliner.reporter.error(msg, line=lineno)
+    prb = inliner.problematic(rawtext, rawtext, msg)
+    return [prb], [msg]
+
+
+def sphinx_ref(options, rawtext, text, ref):
+    set_classes(options)
+    node = nodes.reference(rawtext, text, refuri=ref, **options)
+    return [node], []
+
+
+def role_github_user(name, rawtext, text, lineno, inliner, options=None, content=None):
+    options = options or {}
+    content = content or []
+
+    if not re.match(r"^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$", text):
+        return sphinx_err(inliner, lineno, rawtext, '"%s" is not a valid GitHub username.' % text)
+
+    ref = gh_user_uri.format(text)
+    text = '@' + utils.unescape(text)
+    return sphinx_ref(options, rawtext, text, ref)
 
 
 def role_github_pull_request_or_issue(name, rawtext, text, lineno, inliner, options=None, content=None):
     options = options or {}
     content = content or []
     try:
-        ghid = int(text)
-        if ghid <= 0:
+        if int(text) <= 0:
             raise ValueError
     except ValueError:
-        msg = inliner.reporter.error(
-            'GitHub pull request or issue number must be a number greater than or equal to 1; '
-            '"%s" is invalid.' % text, line=lineno
+        return sphinx_err(
+            inliner, lineno, rawtext,
+            'GitHub pull request or issue number must be a number greater than or equal to 1; "%s" is invalid.' % text
         )
-        prb = inliner.problematic(rawtext, rawtext, msg)
-        return [prb], [msg]
-        # Base URL mainly used by inliner.rfc_reference, so this is correct:
 
     if name == 'pr':
         ref = gh_pr_uri
     elif name == 'issue':
         ref = gh_issue_uri
     else:
-        msg = inliner.reporter.error('unknown tag name for GitHub reference - "%s"' % name, line=lineno)
-        prb = inliner.problematic(rawtext, rawtext, msg)
-        return [prb], [msg]
+        return sphinx_err(inliner, lineno, rawtext, 'unknown role name for GitHub reference - "%s"' % name)
 
-    ref = ref % ghid
-    set_classes(options)
-    node = nodes.reference(rawtext, '#' + utils.unescape(text), refuri=ref, **options)
-    return [node], []
+    ref = ref.format(text)
+    text = '#' + utils.unescape(text)
+    return sphinx_ref(options, rawtext, text, ref)
 
 
 roles.register_local_role('pr', role_github_pull_request_or_issue)
 roles.register_local_role('issue', role_github_pull_request_or_issue)
+roles.register_local_role('ghuser', role_github_user)