В настоящее время я документирую API для отдыха, написанный на Python. Вся проектная документация создается с использованием Sphinx, а для REST API я хотел бы создать некоторые специальные директивы. Например, предположим, что я определил этот ресурс:
@resource("/user/<email>", method="GET")
def user_details (email):
""" Returns detailed information about a user account.
:resource GET: /user/<email>
:query_param a_param: Some kind of query param.
"""
# Do stuff and return user details
В основном, как выглядит документация. Я хотел бы иметь возможность создать директиву для Sphinx, который форматирует один или несколько из этих :query_param ...:, как это происходит с обычным :param:.
Я нашел, как создавать роли, но они работают только в строгом, а не в блоках данных.
Как я должен это сделать?
Sphinx может быть дополнен пользовательскими директивами через " Sphinx Extensions". То есть вам нужно будет реализовать расширение Sphinx, предоставляющее настраиваемую директиву query_param, и добавьте это расширение в свой проект Sphinx.
Документация Sphinx предоставляет учебник по внедрению расширений, в котором они действительно реализуют пользовательскую директиву.
Ссылка: