docs: add highlight plugin for prism in docsify and use it where lines have to be added

- enhance documentation

Author: Mairu

.github_changelog_generator

@@ -5,3 +5,4 @@ release-branch=master
 issues-of-open-milestones=false
 unreleased=false
 output=docs/CHANGELOG.md
+exclude-tags-regex=.*-pre.*

docs/api.md

@@ -39,10 +39,12 @@ __Options:__
 - `versionPrefix` (*optional*) - Used for automatic tag and name generation for services
 - `include` (*optional*) - Object to configure for which services documentation will be generated, empty means all will be included:
   - `tags` - Array of tags for that service documentation will be generated
-  - `paths` - Array of paths (string or regex) for that service documentation will be generated, Notice: paths don't start with /
+  - `paths` - Array of paths (string or regex) for that service documentation will be generated, __Notice:__ paths don't start with /
+  - `filter(service, path)` - Function to filter services for that documentation will be generated, __Notice:__ paths don't start with /
 - `ignore` (*optional*) - Object to configure  to ignore with the following keys:
   - `tags` - Array of tags for that no service documentation will be generated
   - `paths` - Array of paths (string or regex) for that no service documentation will be generated, Notice: paths don't start with /
+  - `filter(service, path)` - Function to filter services for that documentation won't be generated, __Notice:__ paths don't start with /
 - `appProperty` (*optional*, default: `docs`) - Property of the feathers app object that the generated specification will be saved to, allows custom post-processing; set empty to disable
 - `defaults` (*optional*) - Object to customize the defaults for generation of the specification
   - `getOperationArgs({ service, path, config, apiPath, version })` - Function to generate args that the methods for operations will consume, can also customize default tag and model generation

docs/custom-methods.md

@@ -109,6 +109,6 @@ Check out the [example](/examples/custom_methods.md) to see it in action.
 
 ## Limitations
 
-- In Feathers 4 the custom methods are registered after the default methods of a service and therefor
-  the /service/:id route will "win" over a /server/custom route for all methods but POST.
+- In Feathers 4 the custom methods are registered after the default methods of a service and therefore
+  the /service/:id route will "win" over a /service/custom route for all methods but POST.
 - At least one default method has to be existent in a service to be registered

docs/docsify/prism-lines.js

@@ -0,0 +1,93 @@
+function install (hook, vm) {
+  const codeContainer = {
+    counter: 0,
+    codes: {}
+  };
+
+  hook.beforeEach(function (content) {
+    codeContainer.counter = 0;
+    codeContainer.codes = {};
+    return content;
+  });
+
+  hook.mounted(function () {
+    if (vm.compiler._marked.Renderer.prototype.code) {
+      const original = vm.compiler._marked.defaults.renderer.code;
+
+      const code = (code, infostring, escaped) => {
+        const infostringParts = infostring.split(' ');
+        let options;
+
+        if (infostringParts.length > 1) {
+          const [lang, ...rest] = infostringParts;
+          infostring = lang;
+          try {
+            options = JSON.parse(rest.join(' '));
+          } catch (e) {
+            console.error('invalid code options');
+          }
+        }
+
+        const originalResult = original(code, infostring, escaped);
+
+        if (typeof options === 'object') {
+          let { lineNumbers, highlight } = options;
+
+          if (typeof lineNumbers === 'boolean') {
+            lineNumbers = { enabled: lineNumbers };
+          } else if (typeof lineNumbers === 'number') {
+            lineNumbers = { enabled: true, start: lineNumbers };
+          }
+
+          const additionalAttributes = [];
+          if (typeof lineNumbers === 'object') {
+            if (lineNumbers.enabled) {
+              additionalAttributes.push(`class="language-${infostring} line-numbers"`);
+            }
+            if (lineNumbers.start) {
+              additionalAttributes.push(`data-start="${lineNumbers.start}"`);
+            }
+          }
+
+          if (typeof highlight === 'string') {
+            highlight = { line: highlight };
+          }
+
+          if (typeof highlight === 'object') {
+            if (highlight.line) {
+              additionalAttributes.push(`data-line="${highlight.line}"`);
+            }
+            if (highlight.lineOffset) {
+              additionalAttributes.push(`data-line-offset="${highlight.lineOffset}"`);
+            }
+          }
+
+          if (additionalAttributes.length) {
+            codeContainer.codes[codeContainer.counter] = code;
+            additionalAttributes.push(`data-code-counter="${codeContainer.counter}"`);
+            codeContainer.counter += 1;
+
+            return originalResult.replace(/^<pre /, `<pre ${additionalAttributes.join(' ')} `);
+          }
+        }
+
+        return originalResult;
+      };
+
+      vm.compiler._marked.use({ renderer: { code } });
+    }
+  });
+
+  hook.doneEach(function () {
+    document.querySelector('#main').querySelectorAll('pre[data-code-counter]').forEach(pre => {
+      const env = {
+        code: codeContainer.codes[pre.dataset.codeCounter],
+        element: pre.querySelector(':scope > code')
+      };
+
+      window.Prism.hooks.run('complete', env);
+    });
+  });
+}
+
+window.$docsify.plugins = [].concat(install, window.$docsify.plugins);

docs/docsify/replace.js

@@ -0,0 +1,17 @@
+function install (hook) {
+  let replacements;
+
+  hook.mounted(function () {
+    replacements = window.$docsify.replacements || [];
+  });
+
+  hook.beforeEach(function (content) {
+    let modifiedContent = content;
+    replacements.forEach(({ search, replace }) => {
+      modifiedContent = modifiedContent.replace(search, replace);
+    });
+    return modifiedContent;
+  });
+}
+
+window.$docsify.plugins = [].concat(install, window.$docsify.plugins);

docs/examples/authentication_v5.md

@@ -30,7 +30,7 @@
 2. Add documentation to the authentication service (`src/authentication.ts`).
    This example shows local authentication.
 
-   ```typescript
+   ```typescript {"highlight": "12-16, 21-71", "lineNumbers": true}
    import { AuthenticationService, JWTStrategy } from '@feathersjs/authentication';
    import { LocalStrategy } from '@feathersjs/authentication-local';
    import type { Application } from './declarations';
@@ -117,10 +117,11 @@
 4. If you want to provide simple authentication usage on the SwaggerUI using Email/Username and Password,
    you can use the [Swagger UI Plugin ApiKeyAuthForm](https://github.com/Mairu/swagger-ui-apikey-auth-form).
 
-   Here is an example of an `openapi.ts` swagger configuration file, that can used with `api.configure()`;
+   Here is an example of an `openapi.ts` swagger configuration file, that can used with `api.configure();`
 
    ```typescript
-   import swagger, { FnSwaggerUiGetInitializerScript } from 'feathers-swagger';
+   import swagger from 'feathers-swagger';
+   import type { FnSwaggerUiGetInitializerScript } from 'feathers-swagger';
    import type { Application } from './declarations';
 
    const getSwaggerInitializerScript: FnSwaggerUiGetInitializerScript = ({ docsJsonPath, ctx }) => {

docs/examples/custom_methods.md

@@ -1,7 +1,7 @@
 ## Custom Methods <!-- {docsify-ignore} -->
 
 ### Code (from example app) <!-- {docsify-ignore} -->
-[filename](https://raw.githubusercontent.com/feathersjs-ecosystem/feathers-swagger/master/example/openapi-v3/customMethods.js ':include')
+[filename](https://raw.githubusercontent.com/feathersjs-ecosystem/feathers-swagger/{GITHUB_BRANCH}/example/openapi-v3/customMethods.js ':include')
 
 ### Preview in SwaggerUI <!-- {docsify-ignore} -->
 

docs/examples/generated_service_v5.md

@@ -2,7 +2,7 @@
 
 1. Go into your `src/services/{$name}` folder, and open the service you want to edit `${name}.[tj]s`
 2. Import the helper function and import the schemas (example for user service):
-```js
+```js  {"highlight": "9-11", "lineNumbers": true}
   import { createSwaggerServiceOptions } from 'feathers-swagger';
   import {
       userDataValidator,
@@ -11,14 +11,13 @@
       userDataResolver,
       userQueryResolver,
       userExternalResolver,
-      // the lines below are added
       userDataSchema,
       userQuerySchema,
       userSchema,
   } from './users.schema';
 ```
 adjust the options when the service is generated
-```js
+```js {"highlight": "6-12", "lineNumbers": true}
   app.use('users', new UserService(getOptions(app)), {
       // A list of all methods this service exposes externally
       methods: ['find', 'get', 'create', 'update', 'patch', 'remove'],

docs/examples/index.md

@@ -1,6 +1,6 @@
 ## Examples <!-- {docsify-ignore} -->
 
-In addition to the examples you can access from the navigation, you can check out the [example application](https://github.com/feathersjs-ecosystem/feathers-swagger/tree/master/example) of the git repository.
+In addition to the examples you can access from the navigation, you can check out the [example application](https://github.com/feathersjs-ecosystem/feathers-swagger/tree/{GITHUB_BRANCH}/example) of the git repository.
 
 It contains many configurations and can be start with `npm start` when feathers-swagger have been checked out.
 

docs/getting-started.md

@@ -5,7 +5,7 @@
 
 Add [OpenAPI](https://swagger.io/resources/open-api/) documentation to your Feathers services and optionally show them in the [Swagger UI](https://swagger.io/tools/swagger-ui/).
 
-You can also add custom methods to feathers services that will be available as rest routes but not via the feathers client. 
+You can also add custom methods to feathers services that will be available as rest routes but not via feathers client. 
 
 This version is prepared to work with Swagger UI >= 4.9
 

docs/index.html

@@ -8,6 +8,8 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
   <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
   <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-changelog-plugin@latest/dist/style.css">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/prismjs@1/plugins/line-highlight/prism-line-highlight.min.css">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/prismjs@1/plugins/line-numbers/prism-line-numbers.min.css">
   <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
   <style>
     #CHANGELOG_RENDERER {
@@ -18,6 +20,25 @@
     iframe.swui-preview {
       height: 80vh;
     }
+
+    .line-highlight {
+      margin-top: 3.5em;
+    }
+
+    .markdown-section pre[data-line] {
+      overflow: hidden;
+    }
+
+    .markdown-section pre.line-numbers > code {
+      overflow: visible;
+    }
+
+    .markdown-section pre.line-numbers .line-numbers-rows {
+      margin-top: 2.2em;
+    }
+    .markdown-section pre.line-numbers .line-highlight {
+      margin-top: 1em;
+    }
   </style>
 </head>
 <body>
@@ -32,13 +53,23 @@
       subMaxLevel: 3,
       loadNavbar: false,
       changelog: 'CHANGELOG.md',
+      replacements: [
+        {
+          search: '{GITHUB_BRANCH}',
+          replace: 'next'
+        }
+      ],
     }
   </script>
   <!-- Docsify v4 -->
   <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
   <script src="//cdn.jsdelivr.net/npm/docsify-changelog-plugin@latest/dist/index.js"></script>
   <script src="//cdn.jsdelivr.net/npm/docsify-tabs@1"></script>
   <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-typescript.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/plugins/line-highlight/prism-line-highlight.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/plugins/line-numbers/prism-line-numbers.min.js"></script>
   <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>
+  <script src="/docsify/prism-lines.js"></script>
+  <script src="/docsify/replace.js"></script>
 </body>
 </html>

docs/migrations/MIGRATIONS_v1.md

@@ -108,7 +108,7 @@ swagger({
 ### Generate RFC3986-compliant percent-encoded URIs
 
 To generate valid specifications there may not be spaces in $ref links.
-Therefor concatenation is done with _ by default now. This applies to list and version refs of the previous version.
+Therefore concatenation is done with _ by default now. This applies to list and version refs of the previous version.
 
 #### Before
 ```js

docs/migrations/MIGRATIONS_v2.md

@@ -53,7 +53,7 @@ swagger({
 ### docsPath option is removed and a default value for docsJsonPath has been added
 
 As the uiIndex has been removed and the initialization of the ui has been extracted (to the swaggerUI initializer), the docsPath option has been removed / moved to the swaggerUI initializer.
-Therefor the docsJsonPath now has the default value of `/swagger.json`.
+Therefore the docsJsonPath now has the default value of `/swagger.json`.
 
 ### Default of openApiVersion option was changed from 2 to 3
 

example/openapi-v3/customMethods.js

@@ -23,7 +23,7 @@ module.exports = (app) => {
     customPost: swagger.customMethod('POST', '/do-post')((data, params) => {
       return Promise.resolve({ method: 'customPost', data, params });
     }),
-    customPatchWithId: swagger.customMethod('PUT', '/do-patch-with/:__feathersId')(
+    customUpdateWithId: swagger.customMethod('PUT', '/do-patch-with/:__feathersId')(
       (data, params, id) => {
         return Promise.resolve({ method: 'customPatchWithId', id, data, params });
       }
@@ -98,8 +98,8 @@ module.exports = (app) => {
     refs: {
       customPostRequest: 'custom_request',
       customPostResponse: 'custom_response',
-      customPatchWithIdRequest: 'custom_request',
-      customPatchWithIdResponse: 'custom_response'
+      customUpdateWithIdRequest: 'custom_request',
+      customUpdateWithIdResponse: 'custom_response'
     },
     operations: {
       find: {
@@ -190,6 +190,6 @@ module.exports = (app) => {
     .use(
       '/v3/custom-methods/:pathParamName/service',
       service,
-      { methods: ['find', 'customPost', 'customPatchWithId', 'customGetWithCustomIds'] }
+      { methods: ['find', 'customPost', 'customUpdateWithId', 'customGetWithCustomIds'] }
     );
 };

package.json

@@ -26,7 +26,7 @@
     "node": ">= 14"
   },
   "scripts": {
-    "publish": "git push origin --tags && npm run changelog && git push origin",
+    "publish": "git push origin --tags",
     "release:patch": "npm version patch && npm publish",
     "release:minor": "npm version minor && npm publish",
     "release:major": "npm version major && npm publish",