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' | 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_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 89a33f8..5b5d990 100644 --- a/rest_framework_docs/api_endpoint.py +++ b/rest_framework_docs/api_endpoint.py @@ -3,14 +3,17 @@ 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): + 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 @@ -67,7 +70,12 @@ def __get_allowed_methods__(self): return viewset_methods + view_methods def __get_docstring__(self): - return inspect.getdoc(self.callback) + description = inspect.getdoc(self.callback) + 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", "")