{
"info": {
"author": "Daniil Minukhin",
"author_email": "ddddsa@gmail.com",
"bugtrack_url": null,
"classifiers": [
"Development Status :: 5 - Production/Stable",
"Environment :: Console",
"Intended Audience :: Developers",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
"Programming Language :: Python",
"Topic :: Documentation",
"Topic :: Utilities"
],
"description": "# apilinks Preprocessor for Foliant\n\nPreprocessor for replacing API *reference*s in markdown files with links to actual method description on the API documentation web-page.\n\n## Installation\n\n```shell\n$ pip install foliantcontrib.apilinks\n```\n\n## Quick Start\n\nSay, you have an API documentation hosted at the url http://example.com/api-docs\n\nOn this page you have HTML headings before each method description which look like this:\n\n```html\n
GET user/authenticate
\n```\n\nYou want references to these methods in your documentation to be replaced with the links to the actual method descriptions. Your references look like this:\n\n```\nTo authenticate user use API method `GET user/authenticate`.\n```\n\nNow all you need to do is add the apilinks preprocessor into your foliant.yml and state your API url in its options like this:\n\n```yaml\npreprocessors:\n - apilinks:\n API:\n My-API:\n url: http://example.com/api-docs\n```\n\nHere:\n\n- `API` is a required section;\n- `My-API` is a local name of your API. Right now it is not very important but will come in handy in the next example;\n- `url` is a string with full url to your API documentation web-page. It will be used to validate references and to construct a link to method.\n\nAfter foliant applies the preprocessor your document will be transformed into this:\n\n```\nTo authenticate user use API method [GET user/authenticate](http://example.com/api-docs/#get-user-authenticate).\n```\n\nNotice that preprocessor figured out the correct anchor `#get-user-authenticate` by himself. Now instead of plain name of the method you've got a link to the method description!\n\nOk, what if I have two different APIs: client API and admin API?\n\nNo problem, put both of them into your config:\n\n```yaml\npreprocessors:\n - apilinks:\n API:\n Client-API:\n url: http://example.com/client/api-docs\n Admin-API:\n url: http://example.com/admin/api-docs\n```\n\nNow this source:\n\n```\nTo authenticate user use API method `GET user/authenticate`.\nTo ban user from the website use admin API method `POST admin/ban_user/{user_id}`\n```\n\nWill be transformed by apilinks into this:\n\n```\nTo authenticate user use API method [GET user/authenticate](http://example.com/client/api-docs/#get-user-authenticate).\nTo ban user from the website use admin API method [POST admin/ban_user/{user_id}](http://example.com/admin/api-docs/#post-admin-ban_user-user_id)\n```\n\nNotice that apilinks determined that the first reference is from Client API, and the second one is from the Admin API. How is that possible? Easy: preprocessor parses each API url from the config and stores their methods before looking for references. When the time comes to process the references it already has a list of all methods to validate your reference and to determine which API link should be inserted.\n\nBut what if we have the same-named method in both of our APIs? In this case you will see a warning:\n\n```\nWARNING: GET /service/healthcheck is present in several APIs (Client-API, Admin-API). Please, use prefix. Skipping\n```\n\nIt suggests us to use prefix, and by that it means to prefix the reference by the local name of the API in config. Like that:\n\n```\nCheck status of the server through Client API: `Client-API: GET /service/healthcheck`\nDo the same through Admin API: `Admin-API: GET /service/healthcheck`\n```\n\nHere `Client-API: ` and `Admin-API: ` are prefixes. And they should be the same as your API names in the config.\n\nNow each reference will be replaced with the link to corresponding API web-page.\n\n***\n\napilinks is a highly customizable preprocessor. You can tune:\n\n- the format of the references;\n- the output string which will replace the reference;\n- the format of the headings in your API web-page;\n- and more!\n\nFor details look through the following sections.\n\nGlossary:\n\n- **reference** \u2014 reference to an API method in the source file. The one to be replaced with the link, e.g. `GET user/config`\n- **verb** \u2014 HTTP method, e.g. `GET`, `POST`, etc.\n- **command** \u2014 resource used to represent method on the API documentation webpage, e.g. `/service/healthcheck`.\n- **endpoint prefix** \u2014 A prefix from server root to the command. If the command is `/user/status` and full resource is `/api/v0/user/satus` then the endpoint-prefix should be stated `/api/v0`. In references you can use either full resource (`{endpoint_prefix}/{command}`) or just the command. apilinks will sort it out for you.\n- **output** \u2014 string, which will replace the *reference*.\n- **header** \u2014 HTML header on the API documentation web-page of the method description, e.g. `
GET user/config
`\n- **anchor** \u2014 web-anchor leading to the specific *header* on the API documentation web-page, e.g. `#get-user-config`\n\n## How Does It Work?\n\nPreprocessor can work in *online* and *offline* modes.\n\n**In offline mode** it merely replaces *references* to API methods with links to their description. The references are catched by a regular expression. The link url is taken from config and the link *anchor* is generated from the reference automatically.\n\nYou can have several different APIs stated in the config. You can use prefixes to point out which API is being *reference*d. Prefixes format may be customized in the configuration but by default you do it like this: `Client-API: GET user/name`. Here '*Client-API*' is a prefix.\n\nIf you don't use prefix in the *reference* preprocessor will suppose that you meant the default API, which is marked by `default` option in config. If none of them is marked \u2014 goes for the first in list.\n\n**In online mode** things are getting interesting. Preprocessor actually goes to each of the API web-pages, and collects all method **headers** (right now only `h2` headers are supported). Then it goes through your document's source: when it meets a *reference*, it looks through all the collected methods and replaces the reference with the correct link to it. If method is not found \u2014 preprocessor will show warning and leave the reference unchanged. Same will happen if there are several methods with this name in different APIs.\n\nPrefixes, explained before, are supported too.\n\n## Config\n\nTo enable the preprocessor, add `apilinks` to `preprocessors` section in the project config:\n\n```yaml\npreprocessors:\n - apilinks\n```\n\nThe preprocessor has a lot of options. For your convenience the required options are marked *(required)*; and those options which are used in customization are marked *(optional)*. Most likely you will need just one or two of the latter.\n\n```yaml\npreprocessors:\n- apilinks:\n targets:\n - site\n offline: False\n trim_if_targets:\n - pdf\n prefix_to_ignore: Ignore\n reference:\n - regex: *ref_pattern\n only_with_prefixes: false\n only_defined_prefixes: true\n output_template: '[{verb} {command}]({url})'\n trim_template: '`{verb} {command}`'\n API:\n Client-API:\n url: http://example.com/api/client\n default: true\n header_template: '{verb} {command}'\n Admin-API:\n url: http://example.com/api/client\n header_template: '{command}'\n endpoint-prefix: /api/v0\n```\n\n\n`prefix_to_ignore`\n: *(optional)* A default prefix for ignoring references. If apilinks meets a reference with this prefix it leaves it unchanged. Default: `Ignore`\n\n`targets`\n: *(optional)* List of supported targets for `foliant make` command. If target is not listed here \u2014 preprocessor won't be applied. If the list is empty \u2014 preprocessor will be applied for any target. Default: `[]`\n\n`offline`\n: *(optional)* Option determining whether the preprocessor will work in *online* or *offline* mode. Details in the **How Does It Work?** and **Online and Offline Modes Comparison** sections. Default: `False`\n\n`trim_if_targets`\n: *(optional)* List of targets for `foliant make` command for which the prefixes from all *references* in the text will be cut out. Default: `[]`\n\n> Only those references whose prefixes are defined in the `API` section (described below) are affected by this option. All references with unlisted prefixes will not be trimmed.\n\n`reference`\n: *(optional)* A subsection for listing all the types of references you are going to catch in the text, and their properties. Options for this section are listed below.\n\n***\n\n**Reference options**\n`regex`\n: *(optional)* regular expression used to catch *references* in the source. Look for details in the **Capturing References** section.\nDefault:\n\n```\n(?P`((?P[\\w-]+):\\s*)?(?POPTIONS|GET|HEAD|POST|PUT|DELETE|TRACE|CONNECT|PATCH|LINK|UNLINK)\\s+(?P\\S+)`)\n```\n\n`only_with_prefixes`\n: *(optional)* if this is `true`, only *references* with prefix will be transformed. Ordinary links like `GET user/info` will be ignored. Default: `false`\n\n`only_defined_prefixes`\n: *(optional)* if this is `true` all references whose prefix is not listed in the `API` section (described below) will be ignored, left unchanged. References without prefix are not affected by this option. Default: `false`.\n\n`output_template`\n: *(optional)* A template string describing the *output* which will replace the *reference*. More info in the **Customizing Output** section. Default: `'[{verb} {command}]({url})'`\n\n`trim_template`\n: *(optional)* Only for targets listed in `trim_if_targets` option. Tune this template if you want to customize how apilinks cuts out prefixes. The reference will be replaced with text based on this template. Default: ```'`{verb} {command}`'```\n\n***\n\n`API`\n: *(required)* A subsection for listing all the APIs and their properties. Under this section there should be a separate subsection for each API. The section name represents the API name and, at the same time, the *prefix* used in the references. You need to add at least one API subsection for preprocessor to work.\n\n***\n\n**API properties**\n\n`url`\n: *(required)* An API documentation web-page URL. It will be used to construct the full link to the method. In online mode it will also be parsed by preprocessor for validation.\n\n`default`\n: *(optional)* Only for offline mode. Marker to define the default API. If several APIs are marked default, preprocessor will choose the first of them. If none is marked default \u2014 the first API in the list will be chosen. The value of this item should be `true`.\n\n`header_template`\n: *(optional)* A template string describing the format of the headings in the API documentation web-page. Details in **parsing API web-page** section. Default: `'{verb} {command}'`\n\n`endpoint-prefix`\n: *(optional)* The endpoint prefix from the server root to API methods. If is stated \u2014 apilinks can divide the command in the reference and search for it more accurately. Also you could use it in templates. More info coming soon. Default: `''`\n\n## Online and Offline Modes Comparison\n\nLet's study an example and look how the behavior of the preprocessor will change in online and offline modes.\n\nWe have three APIs described in the config:\n\n```yaml\npreprocessors:\n - apilinks:\n API:\n Admin-API:\n url: http://example.com/api/client\n Client-API:\n url: http://example.com/api/client\n default: true\n header_template: '{verb} {command}'\n Remote-API:\n url: https://remote.net/api-ref/\n header_template: '{command}'\n```\n\nNow let's look at different examples of the text used in Markdown source and how it is going to be transformed in Offline and Online modes\n\n**Example 1**\nSource:\n\n```\nUnprefixed link which only exists in Remote API: `GET system/info`.\n```\n\nIn *Offline mode* preprocessor won't do any checks and just replace the reference with the link to default API from the config:\n\n```\nUnprefixed link which only exists in Remote API: [GET system/info](http://example.com/api/client/#get-system-info).\n```\n\nThis is certainly a wrong decision, but it is our fault, we sould have added the prefix to the reference.\n\nBut let's look what will happen in *Online mode*:\n\n```\nUnprefixed link which only exists in Remote API: [GET system/info](https://remote.net/api-ref/#system-info).\n```\n\nWithout any prefix the preprocessor determined that it should choose the Remote API to replace this reference because this method exists only on its page. The `default` option is just ignored in this mode.\n\nBy the way, notice how anchors differ in the two examples. For Remote API preprocessor used its header template to reconstruct the anchor, dropping the verb from it.\n\n**Example 2**\nSource:\n\n```\nUnprefixed link with misprint: `GET user/sttus`.\nThe link is incorrect, there's no such method in any of the APIs.\n```\n\nIn *Offline mode* preprocessor won't do any checks again. No magic, the reference will be replaced with the link to default API from the config:\n\n```\nUnprefixed link with misprint: [GET user/sttus](http://example.com/api/client/#get-user-sttus).\nThe link is incorrect, there's no such method in any of the APIs.\n```\n\nIn *Online mode* preprocessor won't be able to find the method during validation and the reference won't be replaced at all:\n\n```\nUnprefixed link with misprint: `GET user/sttus`.\nThe link is incorrect, there's no such method in any of the APIs.\n```\n\nDuring the Foliant project assembly you will see a warning message:\n\n```\nWARNING: Cannot find method GET user/sttus. Skipping\n```\n\n**Example 3**\nSource:\n\n```\nPrefixed link to the Admin API: `Admin-API: POST user/ban_forever`.\n```\n\nIn *Offline mode* preprocessor will notice the prefix and will be able to replace the reference with an appropriate link:\n\n```\nPrefixed link to the Admin API: [POST user/ban_forever](http://example.com/api/client/#post-user-ban_forever).\n```\n\nNotice that prefix disappeared from the text. If you wish it to stay there \u2014 edit the `output_template` option to something like this: `'{prefix}: {verb} {command}'`.\n\nIn *Online mode* the result will be exactly the same. Preprocessor will check the Admin-API methods, find there the referenced method and replace it in the text:\n\n```\nPrefixed link to the Admin API: [POST user/ban_forever](http://example.com/api/client/#post-user-ban_forever).\n```\n\n**Example 4**\n\n```\nPrefixed link to the Remote API with a misprint: `Remote-API: GET billling/info`.\nOh no, the method is incorrect again.\n```\n\nIn *Offline mode* preprocessor will perform no checks and just replace the reference with the link to Remote API:\n\n```\nPrefixed link to the Remote API with a misprint: [GET billling/info](https://remote.net/api-ref/#get-billling-info).\nOh no, the method is incorrect again.\n```\n\n*Online mode*, on the other hand, will make its homework. It will check whether the Remote API actually has the method *GET billling/info*. Finding out that it hasn't it will leave the reference unchanged:\n\n```\nPrefixed link to the Remote API with a misprint: `Remote-API: GET billling/info`.\nOh no, the method is incorrect again.\n```\n\n...and warn us with the message:\n\n```\nWARNING: Cannot find method GET billling/info in Remote-API. Skipping\n```\n\n**Example 5**\n\n```\nNow let's reference a method which is present in both Client and Admin APIs: `GET service/healthcheck`.\n```\n\nIn *Offline mode* preprocessor will just replace the reference with a link to default API:\n\n```\nNow let's reference a method which is present in both Client and Admin APIs: [GET service/healthcheck](http://example.com/api/client/#get-service-healthcheck).\n```\n\nBut in *Online mode* preprocessor will go through all API method lists. It will find several mentions of this exact method and, confused, won't replace the reference at all:\n\n```\nNow let's reference a method which is present in both Client and Admin APIs: `GET service/healthcheck`.\n```\n\nYou will also see a warning:\n\n```\nWARNING: GET /service/healthcheck is present in several APIs (Admin-API, Client-API). Please, use prefix. Skipping\n```\n\n## Capturing References\n\napilinks uses regular expressions to capture *references* to API methods in Markdown files.\n\nThe default reg-ex is as following:\n\n```re\n(?P`((?P[\\w-]+):\\s*)?(?POPTIONS|GET|HEAD|POST|PUT|DELETE|TRACE|CONNECT|PATCH|LINK|UNLINK)\\s+(?P\\S+)`)\n```\n\nThis expression accepts references like these:\n\n- `Client-API: GET user/info`\n- `UPDATE user/details`\n\n> Notice that default expression uses *Named Capturing Groups*. You would probably want to use all of them too if you are to redefine the expression. Though not all of them are required, see the table below.\n\nGroup | Required | Description\n----- | -------- | -----------\nsource | YES | The full original reference string\nprefix | NO | Prefix pointing to the name of the API from config\nverb | NO | HTTP verb as `GET`, `POST`, etc\ncommand | YES | the full method resource as it is stated in the API header (may include endpoint prefix)\n\nTo redefine the regular expression add an option `reg-regex` to the preprocessor config.\n\nFor example, if you want to capture ONLY references with prefixes you may use the following:\n\n```yaml\npreprocessors:\n - apilinks:\n reference:\n - regex: '(?P`((?P[\\w-]+):\\s*)(?PPOST|GET|PUT|UPDATE|DELETE)\\s+(?P\\S+)`)'\n```\n\n> This example is for illustrative purposes only. You can achieve the same goal by just switching on the `only_with_prefixes` option.\n\nNow the references without prefix (`UPDATE user/details`) will be ignored.\n\n## Customizing Output\n\nYou can customize the *output*-string which will replace the *reference* string. To do that add a template into your config-file.\n\nA *template* is a string which may contain properties, surrounded by curly braces. These properties will be replaced with the values, and all the rest will remain unchanged.\n\nFor example, look at the default template:\n\n```yaml\npreprocessors:\n - apilinks:\n reference:\n - output_template: '[{verb} {command}]({url})',\n```\n\n> Don't forget the single quotes around the template. This way we say to yaml engine that this is a string for it not to be confused with curly braces.\n\nWith the default template, the reference string will be replaced by something like that:\n\n```\n[GET user/info](http://example.com/api/#get-user-info)\n```\n\nIf you don't want references to be transfromed into links, use your own template. Properties you may use in the template:\n\nproperty | description | example\n-------- | ----------- | -------\nurl | Full url to the method description | `http://example.com/api/#get-user-info`\nsource | Full original reference string | \\``Client-API: GET user/info`\\`\nprefix | Prefix used in the reference | `Client-API`\nverb | HTTP verb used in the reference | `GET`\ncommand | API command being referenced with endpoint prefix removed | `user/info`\nendpoint_prefix | Endpoint prefix to the API (if `endpoint-prefix` option is filled in) | `/api/v0`\n\n## Parsing API Web-page\n\napilinks goes through the API web-page content and gathers all the methods which are described there.\n\nTo do this preprocessor scans each HTML `h2` tag and stores its `id` attribute (which is an *anchor* of the link to be constructed) and the contents of the tag (the *heading* itself).\n\nFor example in this link:\n\n```html\n
GET user/info
\n```\n\nthe anchor would be `get-user-info` and the heading would be `GET user/info`.\n\nTo construct the link to the method description we will have to create the correct anchor for it. To create an anchor we would need to reconstruct the heading first. But the heading format may be arbitrary and that's why we need the `header_template` config option.\n\nThe `header_template` is a string which may contain properties, surrounded by curly braces. These properties will be replaced with the values, when preprocessor will attempt to reconstruct the heading. All the rest will remain unchanged.\n\nFor example, if your API headings look like this:\n\n```\n
Method user/info (GET)
\n```\n\nYou should use the following option:\n\n```yaml\n...\nAPI:\n Client-API:\n header_template: 'Method {command} ({verb})'\n...\n```\n\n> Don't forget the single quotes around the template. This way we say to yaml engine that this is a string.\n\nIf your headers do not have a verb at all:\n\n```\n