How to create custom directives in Sphinx
Sphinx can be extended with custom directives via "Sphinx Extensions". That is, you will need to implement a Sphinx extension providing the query_param
custom directive, and add this extension to your Sphinx project.
Sphinx documentation provides a tutorial on implementing extensions, in which they implement a custom directive indeed.
Reference:
http://www.sphinx-doc.org/en/stable/extensions.html
http://www.sphinx-doc.org/en/stable/extdev/index.html#dev-extensions
Blubber
Updated on June 11, 2022Comments
-
Blubber about 2 years
I'm currently documenting a rest API written in Python. All the project's documentation is created using Sphinx, and for the REST API I would like to create some special directives. For instance, let's say I have this resource defined:
@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
That's basically how the documentation currently looks. I would like to be able to create a directive for Sphinx that formats one or more of those
:query_param ...:
just like it does with regular:param:
.I have found how to make roles, but they only work inline, not for blocks of data.
How should I go about making this?
-
John Szakmeister almost 12 yearsYou may want to ask this on the Sphinx Google Group. Someone there might be more capable of answering the question. Off-hand, I'm not sure how documentation blocks are treated. You can certainly create extensions in Sphinx/docutils, but I'm not sure how docstring parsing fits into the Sphinx/docutils model.
-
John Szakmeister almost 12 yearsThe answer probably involves using a GroupedField in your extension though.
-