# mkdocs-apicall-plugin
[](https://github.com/asiffer/mkdocs-apicall-plugin/actions/workflows/build.yaml)
[](https://github.com/asiffer/mkdocs-apicall-plugin/actions/workflows/publish.yaml)
[](https://badge.fury.io/py/mkdocs-apicall-plugin)
Auto-generate code samples to make API calls
## Installation
```shell
pip install mkdocs-apicall-plugin
```
This plugin works with the [material](https://squidfunk.github.io/mkdocs-material/) theme and is built on top of the [`tabbed`](https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/) and [`superfenced`](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/) extensions from PyMdown. Enable the extensions and the plugin in your `mkdocs.yml`:
```yaml
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.
```md
@@@ <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:
```yaml
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:
```yaml
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:
```yaml
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/](https://github.com/asiffer/mkdocs-apicall-plugin/tree/master/mkdocs_apicall_plugin) folder.
Basically a language looks as follows:
```python
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/asiffer/mkdocs-apicall-plugin",
"name": "mkdocs-apicall-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Alban Siffer",
"author_email": "alban@situation.sh",
"download_url": "https://files.pythonhosted.org/packages/42/0d/f914610a9beab0ebe76d5558d1d58ee1fea258b9b9c636caa83ea8cd2d2f/mkdocs_apicall_plugin-0.2.2.tar.gz",
"platform": null,
"description": "# mkdocs-apicall-plugin\n\n[](https://github.com/asiffer/mkdocs-apicall-plugin/actions/workflows/build.yaml)\n[](https://github.com/asiffer/mkdocs-apicall-plugin/actions/workflows/publish.yaml)\n[](https://badge.fury.io/py/mkdocs-apicall-plugin)\n\nAuto-generate code samples to make API calls\n\n\n\n## Installation\n\n```shell\npip install mkdocs-apicall-plugin\n```\n\nThis plugin works with the [material](https://squidfunk.github.io/mkdocs-material/) theme and is built on top of the [`tabbed`](https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/) and [`superfenced`](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/) extensions from PyMdown. Enable the extensions and the plugin in your `mkdocs.yml`:\n\n```yaml\ntheme:\n name: material\n\nmarkdown_extensions:\n - pymdownx.superfences\n - pymdownx.tabbed:\n alternate_style: true\n\nplugins:\n - apicall\n```\n\n\n## Syntax\n\nThe syntax is given below. Basically it may look like a classical HTTP request message.\n\n```md\n@@@ <METHOD> <PATH> [<PAYLOAD>]\n [<HEADER-KEY>: <HEADER-VALUE>]\n [<HEADER-KEY>: <HEADER-VALUE>]\n```\n\nThe method and the paths are both mandatory. \nOne can append a payload (only a json for the moment) to the first line.\nThe following lines are extra indented HTTP headers.\n\n## Configuration\n\nThe plugin supports few options:\n\n**`line_length`** [`int`] is the maximum length of a line of code before splitting into several lines.\n\n**`icons`** [`bool`] activates language icons. You must add the following extensions:\n\n```yaml\nmarkdown_extensions:\n # ... \n - attr_list\n - pymdownx.emoji:\n emoji_index: !!python/name:materialx.emoji.twemoji\n emoji_generator: !!python/name:materialx.emoji.to_svg\n```\n\n\n**`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`.\n\nAs an example you may have:\n\n```yaml\nplugins:\n - apicall:\n line_length: 90\n icons: true\n languages:\n - curl\n - python\n - javascript\n```\n\nYou can also pass extra configuration to a language by adding some sub-keys:\n\n```yaml\nplugins:\n - apicall:\n line_length: 90\n icons: true\n languages:\n - curl:\n options:\n - \"-s\"\n - python\n - javascript\n```\n\nCurrently only `curl` supports the `options` sub-key to insert some CLI options.\n\n## Contributing\n\nObviously, we need to dev more *languages* and increase the number of features: HTTP options, language options, code formatting...\n\n### How?\n\nOpen an issue, we may possibly discuss about the requested feature and if we are OK, you can create a branch and submit PR.\n\n### Developing a new language\n\nTo add a new language, you have to create a new source code file inside the [mkdocs_apicall_plugin/](https://github.com/asiffer/mkdocs-apicall-plugin/tree/master/mkdocs_apicall_plugin) folder.\n\nBasically a language looks as follows:\n\n```python\nfrom .abstract import APICall\n\n\nclass NewAPICall(APICall):\n # [unique] name of the language. This is what is displayed\n # in the tabs\n name: str = \"new\"\n # material mkdocs icons (see https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/)\n icon: str = \":material-web:\" \n # Pygments language for syntax highlighting\n # (see https://pygments.org/languages/)\n lang: str = \"shell\" \n # Indentation when the call is wrapped into several lines\n # This is just for internal use (so it depends on how you\n # code the language)\n indent: str = \" \" * 5\n\n def render_code(self) -> str:\n \"\"\"Single function to implement. It must return the raw \n string that will be encapsulated in code blocks and tabs.\n \"\"\"\n # TODO\n```\n\nSo, you must implement a subclass of `APICall` and notably the `render_code` method. This method returns only the code as string, \nas you may write in your favorite editor.\n\nYou have access to several attributes:\n\n| Attribute | Type | Details |\n| ------------------ | --------------------- | ------------------------------------------------------------------------------------- |\n| `_method` | `abstract.HttpMethod` | Like `GET` or `POST`. This is always uppercase |\n| `_url` | `str` | API endpoint to reach |\n| `_headers` | `Dict[str, Any]` | HTTP headers |\n| `_body` | `str` | Raw body as string (as it is written in the API call within the markdown source file) |\n| `_max_line_length` | `int` | Maximum line length desired |\n| `_print_icon` | `bool` | Whether the icon will be printed (normally it does have impact on your dev) |\n| `_language_config` | `dict` | Language specific configuration |\n\n> [!WARNING] \n> You are responsible of the possible default values of the`_language_config` attribute.\n\n> [!WARNING] \n> 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.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Auto-generate code samples to make API calls",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://github.com/asiffer/mkdocs-apicall-plugin",
"Repository": "https://github.com/asiffer/mkdocs-apicall-plugin"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bd5bb208c4ae4a43f9c4c9edf5c29a187bddda56910439f849ead3f0ec64ce89",
"md5": "60888ae4866e1fe0696b3814c81b94ed",
"sha256": "40a925616a02dbacaec92fb27a1fb0df5ab8d302280cc94b25eeae3a8d79e780"
},
"downloads": -1,
"filename": "mkdocs_apicall_plugin-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "60888ae4866e1fe0696b3814c81b94ed",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13027,
"upload_time": "2024-07-20T13:39:12",
"upload_time_iso_8601": "2024-07-20T13:39:12.010243Z",
"url": "https://files.pythonhosted.org/packages/bd/5b/b208c4ae4a43f9c4c9edf5c29a187bddda56910439f849ead3f0ec64ce89/mkdocs_apicall_plugin-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "420df914610a9beab0ebe76d5558d1d58ee1fea258b9b9c636caa83ea8cd2d2f",
"md5": "805119b35dd26b3c53ef5ace1ef9acac",
"sha256": "4df49c0b5d2b156e98ff2b14a1ba29f211756d09108c330e89d7fef785dbc7b3"
},
"downloads": -1,
"filename": "mkdocs_apicall_plugin-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "805119b35dd26b3c53ef5ace1ef9acac",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12222,
"upload_time": "2024-07-20T13:39:13",
"upload_time_iso_8601": "2024-07-20T13:39:13.416963Z",
"url": "https://files.pythonhosted.org/packages/42/0d/f914610a9beab0ebe76d5558d1d58ee1fea258b9b9c636caa83ea8cd2d2f/mkdocs_apicall_plugin-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-20 13:39:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "asiffer",
"github_project": "mkdocs-apicall-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-apicall-plugin"
}
JSON
