Auto-generate code samples to make API calls
Project description
mkdocs-apicall-plugin
Auto-generate code samples to make API calls
Installation
pip install mkdocs-apicall-plugin
This plugin works with the material theme and is built on top of the tabbed
and superfenced
extensions from PyMdown. Enable the extensions and the plugin in your mkdocs.yml
:
theme:
name: material
markdown_extensions:
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
plugins:
- apicall
Syntax
The syntax is given below. Basically it may look like a classical HTTP request message.
@@@ <METHOD> <PATH> [<PAYLOAD>]
[<HEADER-KEY>: <HEADER-VALUE>]
[<HEADER-KEY>: <HEADER-VALUE>]
The method and the paths are both mandatory. One can append a payload (only a json for the moment) to the first line. The following lines are extra indented HTTP headers.
Configuration
The plugin supports few options:
line_length
[int
] is the maximum length of a line of code before splitting into several lines.
icons
[bool
] activates language icons. You must add the following extensions:
markdown_extensions:
# ...
- attr_list
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
languages
[list
] filters the languages to display (show all by default). The order is also taken into account. The term language is clearly a misuse as it rather refers to a way to make the API call (so we may have curl
, wget
along with typescript
for example). Currently 3 languages are supported: curl
, python
and javascript
.
As an example you may have:
plugins:
- apicall:
line_length: 90
icons: true
languages:
- curl
- python
- javascript
You can also pass extra configuration to a language by adding some sub-keys:
plugins:
- apicall:
line_length: 90
icons: true
languages:
- curl:
options:
- "-s"
- python
- javascript
Currently only curl
supports the options
sub-key to insert some CLI options.
Contributing
Obviously, we need to dev more languages and increase the number of features: HTTP options, language options, code formatting...
How?
Open an issue, we may possibly discuss about the requested feature and if we are OK, you can create a branch and submit PR.
Developing a new language
To add a new language, you have to create a new source code file inside the mkdocs_apicall_plugin/ folder.
Basically a language looks as follows:
from .abstract import APICall
class NewAPICall(APICall):
# [unique] name of the language. This is what is displayed
# in the tabs
name: str = "new"
# material mkdocs icons (see https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/)
icon: str = ":material-web:"
# Pygments language for syntax highlighting
# (see https://pygments.org/languages/)
lang: str = "shell"
# Indentation when the call is wrapped into several lines
# This is just for internal use (so it depends on how you
# code the language)
indent: str = " " * 5
def render_code(self) -> str:
"""Single function to implement. It must return the raw
string that will be encapsulated in code blocks and tabs.
"""
# TODO
So, you must implement a subclass of APICall
and notably the render_code
method. This method returns only the code as string,
as you may write in your favorite editor.
You have access to several attributes:
Attribute | Type | Details |
---|---|---|
_method |
abstract.HttpMethod |
Like GET or POST . This is always uppercase |
_url |
str |
API endpoint to reach |
_headers |
Dict[str, Any] |
HTTP headers |
_body |
str |
Raw body as string (as it is written in the API call within the markdown source file) |
_max_line_length |
int |
Maximum line length desired |
_print_icon |
bool |
Whether the icon will be printed (normally it does have impact on your dev) |
_language_config |
dict |
Language specific configuration |
:warning: You are responsible of the possible default values of the_language_config
attribute.
:warning: You are encouraged to render code differently according to the value of _max_line_length
. One may imagine at least an inline and a multiline rendering.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs_apicall_plugin-0.1.7.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | d0becc42c3c4e676505bbfd84909ec13a02b0eda0e4a879f2ca36cd7054115bf |
|
MD5 | 046d4c39289d2741209a83b1a1d72b95 |
|
BLAKE2b-256 | 7ba178775b22550ef7d8b2ff6e730501e7ea438181ef310c959108829beaed0c |
Hashes for mkdocs_apicall_plugin-0.1.7-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1b7fc27f47fa64978d2ef3ff80bf31bd251f1a3ed8cf839339134241969bc444 |
|
MD5 | d8870a6b3f384a770d483e0eb3af934d |
|
BLAKE2b-256 | 76145ac24f0c7ef13878443ea0f66ec688f4aa886e39a0bfd43954ae5b09cc15 |