HTML Documentation generation¶
Django-modern-rpc can optionally process the docstring attached to your RPC methods and display it in a web page. This article will explain how generated documentation can bu used and customized.
Enable documentation¶
RPCEntryPoint class can be configured to provide HTML documentation of your RPC methods.
To enable the feature, simply set enable_doc = True
in your view instance
urlpatterns = [
# Configure the RPCEntryPoint directly by passing some arguments to as_view() method
url(r'^rpc/', RPCEntryPoint.as_view(enable_doc=True)),
]
If you prefer provide documentation on a different URL than the one used to handle RPC requests, you just need to specify two different URLConf.
urlpatterns = [
# By default, RPCEntryPoint does NOT provide documentation but handle RPC requests
url(r'^rpc/', RPCEntryPoint.as_view()),
# And you can configure it to display doc without handling RPC requests.
url(r'^rpc-doc/', RPCEntryPoint.as_view(enable_doc=True, enable_rpc=False)),
]
Customize rendering¶
By default, documentation will be rendered using a Bootstrap 4 based template with collapse component, to display doc in a list of accordion widgets.
You can customize the documentation page by setting your own template. RPCEntryPoint
inherits
django.views.generic.base.TemplateView
, so you have to set view’s template_name
attribute:
urlpatterns = [
# Configure the RPCEntryPoint directly by passing some arguments to as_view() method
url(r'^rpc/', RPCEntryPoint.as_view(
enable_doc=True,
template_name='my_app/my_custom_doc_template.html'
)
),
]
In the template, you will get a list of modernrpc.core.RPCMethod
instance (one per registered RPC method). Each
instance of this class has some methods and properties to retrieve documentation.
Write documentation¶
The documentation is generated directly from RPC methods docstring
@rpc_method(name="util.printContentType")
def content_type_printer(**kwargs):
"""
Inspect request to extract the Content-Type heaser if present.
This method demonstrate how a RPC method can access the request object.
:param kwargs: Dict with current request, protocol and entry_point information.
:return: The Content-Type string for incoming request
"""
# The other available variables are:
# protocol = kwargs.get(MODERNRPC_PROTOCOL_PARAM_NAME)
# entry_point = kwargs.get(MODERNRPC_ENTRY_POINT_PARAM_NAME)
# Get the current request
request = kwargs.get(REQUEST_KEY)
# Return the content-type of the current request
return request.META.get('Content-Type', '')
If you want to use Markdown or reStructuredText syntax in your RPC method documentation, you have to install the corresponding package in you environment.
pip install Markdown
or
pip install docutils
Then, set settings.MODERNRPC_DOC_FORMAT
to indicate which parser must be used to process your docstrings
# In settings.py
MODERNRPC_DOC_FORMAT = 'markdown'
or
# In settings.py
MODERNRPC_DOC_FORMAT = 'rst'