From bb4258e3c95ff476aceeb6cc566ea77ce73ad1ff Mon Sep 17 00:00:00 2001 From: Priji Date: Fri, 22 Jul 2016 19:52:54 +0530 Subject: [PATCH 1/4] Support reStructuredText in docstring --- requirements.txt | 1 + rest_framework_docs/api_endpoint.py | 7 ++++++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index f449bbb..d425ed1 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,3 +3,4 @@ djangorestframework==3.3.2 coverage==4.0.3 flake8==2.5.1 mkdocs==0.15.3 +docutils==0.12 diff --git a/rest_framework_docs/api_endpoint.py b/rest_framework_docs/api_endpoint.py index 89a33f8..2053fb0 100644 --- a/rest_framework_docs/api_endpoint.py +++ b/rest_framework_docs/api_endpoint.py @@ -4,6 +4,8 @@ from django.utils.encoding import force_str from rest_framework.serializers import BaseSerializer +from django.utils.safestring import mark_safe +from docutils import core class ApiEndpoint(object): @@ -67,7 +69,10 @@ def __get_allowed_methods__(self): return viewset_methods + view_methods def __get_docstring__(self): - return inspect.getdoc(self.callback) + description = inspect.getdoc(self.callback) + parts = core.publish_parts(source = description, writer_name = 'html') + html = parts['body_pre_docinfo'] + parts['fragment'] + return mark_safe(html) def __get_permissions_class__(self): for perm_class in self.pattern.callback.cls.permission_classes: From 6f1751d6891ab3d5b6a27cac207138071103e69a Mon Sep 17 00:00:00 2001 From: Priji Date: Fri, 22 Jul 2016 21:44:43 +0530 Subject: [PATCH 2/4] Added setting DOCSTRING_FORMAT --- rest_framework_docs/api_docs.py | 5 +++-- rest_framework_docs/api_endpoint.py | 11 +++++++---- rest_framework_docs/settings.py | 3 ++- rest_framework_docs/views.py | 2 +- 4 files changed, 13 insertions(+), 8 deletions(-) diff --git a/rest_framework_docs/api_docs.py b/rest_framework_docs/api_docs.py index d22dd4c..1d9f0da 100644 --- a/rest_framework_docs/api_docs.py +++ b/rest_framework_docs/api_docs.py @@ -8,9 +8,10 @@ class ApiDocumentation(object): - def __init__(self, drf_router=None): + def __init__(self, drf_router=None, docstring_format=None): self.endpoints = [] self.drf_router = drf_router + self.docstring_format = docstring_format try: root_urlconf = import_string(settings.ROOT_URLCONF) except ImportError: @@ -27,7 +28,7 @@ def get_all_view_names(self, urlpatterns, parent_pattern=None): parent_pattern = None if pattern._regex == "^" else pattern self.get_all_view_names(urlpatterns=pattern.url_patterns, parent_pattern=parent_pattern) elif isinstance(pattern, RegexURLPattern) and self._is_drf_view(pattern) and not self._is_format_endpoint(pattern): - api_endpoint = ApiEndpoint(pattern, parent_pattern, self.drf_router) + api_endpoint = ApiEndpoint(pattern, parent_pattern, self.drf_router, self.docstring_format) self.endpoints.append(api_endpoint) def _is_drf_view(self, pattern): diff --git a/rest_framework_docs/api_endpoint.py b/rest_framework_docs/api_endpoint.py index 2053fb0..30a6ae7 100644 --- a/rest_framework_docs/api_endpoint.py +++ b/rest_framework_docs/api_endpoint.py @@ -9,10 +9,11 @@ class ApiEndpoint(object): - def __init__(self, pattern, parent_pattern=None, drf_router=None): + def __init__(self, pattern, parent_pattern=None, drf_router=None, docstring_format=None): self.drf_router = drf_router self.pattern = pattern self.callback = pattern.callback + self.docstring_format = docstring_format # self.name = pattern.name self.docstring = self.__get_docstring__() self.name_parent = simplify_regex(parent_pattern.regex.pattern).strip('/') if parent_pattern else None @@ -70,9 +71,11 @@ def __get_allowed_methods__(self): def __get_docstring__(self): description = inspect.getdoc(self.callback) - parts = core.publish_parts(source = description, writer_name = 'html') - html = parts['body_pre_docinfo'] + parts['fragment'] - return mark_safe(html) + if (self.docstring_format == "rst"): # reStructuredText + parts = core.publish_parts(source=description, writer_name="html") + html = parts["body_pre_docinfo"] + parts["fragment"] + description = mark_safe(html) + return description def __get_permissions_class__(self): for perm_class in self.pattern.callback.cls.permission_classes: diff --git a/rest_framework_docs/settings.py b/rest_framework_docs/settings.py index 2853a7b..a2f06e9 100644 --- a/rest_framework_docs/settings.py +++ b/rest_framework_docs/settings.py @@ -5,7 +5,8 @@ class DRFSettings(object): def __init__(self): self.drf_settings = { - "HIDE_DOCS": self.get_setting("HIDE_DOCS") or False + "HIDE_DOCS": self.get_setting("HIDE_DOCS") or False, + "DOCSTRING_FORMAT": self.get_setting("DOCSTRING_FORMAT") or "text" } def get_setting(self, name): diff --git a/rest_framework_docs/views.py b/rest_framework_docs/views.py index 50400d4..c894efb 100644 --- a/rest_framework_docs/views.py +++ b/rest_framework_docs/views.py @@ -15,7 +15,7 @@ def get_context_data(self, **kwargs): raise Http404("Django Rest Framework Docs are hidden. Check your settings.") context = super(DRFDocsView, self).get_context_data(**kwargs) - docs = ApiDocumentation(drf_router=self.drf_router) + docs = ApiDocumentation(drf_router=self.drf_router, docstring_format=settings["DOCSTRING_FORMAT"]) endpoints = docs.get_endpoints() query = self.request.GET.get("search", "") From faa36c5191ef164e1eee9228fe08a7218b522b84 Mon Sep 17 00:00:00 2001 From: Priji Date: Fri, 22 Jul 2016 22:12:05 +0530 Subject: [PATCH 3/4] Added documentation for setting DOCSTRING_FORMAT --- README.md | 1 + docs/settings.md | 13 +++++++++---- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6c82768..7ee6e05 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,7 @@ You can find detailed information about the package's settings at [the docs](htt REST_FRAMEWORK_DOCS = { 'HIDE_DOCS': True # Default: False + 'DOCSTRING_FORMAT': 'rst' # Default: 'text' } diff --git a/docs/settings.md b/docs/settings.md index abd2106..5d9fb40 100755 --- a/docs/settings.md +++ b/docs/settings.md @@ -21,9 +21,14 @@ You can use hidden to prevent your docs from showing up in different environment Then set the value of the environment variable `HIDE_DRFDOCS` for each environment (ie. Use `.env` files) +##### DOCSTRING_FORMAT +Use DOCSTRING_FORMAT to configure the format you follow for the docstrings. Supported formats are: +- *text*: Plain text +- *rst*: reStructuredText + ### List of Settings -| Setting | Type | Options | Default | -|---------|---------|-----------------|---------| -|HIDE_DOCS| Boolean | `True`, `False` | `False` | -| | | | | +| Setting | Type | Options | Default | +|----------------|---------|-----------------|---------| +|HIDE_DOCS | Boolean | `True`, `False` | `False` | +|DOCSTRING_FORMAT| String | 'text', 'rst' | 'text' | From 35ca9db602fb74b92e08112472008994f901b666 Mon Sep 17 00:00:00 2001 From: Priji Date: Sat, 23 Jul 2016 08:44:17 +0530 Subject: [PATCH 4/4] Fixed build errors --- rest_framework_docs/api_endpoint.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rest_framework_docs/api_endpoint.py b/rest_framework_docs/api_endpoint.py index 30a6ae7..5b5d990 100644 --- a/rest_framework_docs/api_endpoint.py +++ b/rest_framework_docs/api_endpoint.py @@ -3,10 +3,10 @@ from django.contrib.admindocs.views import simplify_regex from django.utils.encoding import force_str from rest_framework.serializers import BaseSerializer - from django.utils.safestring import mark_safe from docutils import core + class ApiEndpoint(object): def __init__(self, pattern, parent_pattern=None, drf_router=None, docstring_format=None): @@ -71,7 +71,7 @@ def __get_allowed_methods__(self): def __get_docstring__(self): description = inspect.getdoc(self.callback) - if (self.docstring_format == "rst"): # reStructuredText + if (self.docstring_format == "rst"): # reStructuredText parts = core.publish_parts(source=description, writer_name="html") html = parts["body_pre_docinfo"] + parts["fragment"] description = mark_safe(html)