docs: release as asset (#11429)

* docs: prepare release as asset

* chore: cleanup

* fix: wrong extension

* fix: wrong logger

* fix: wrong path

* chore: clean and create tmp

* chore: fix types

* fix: update generation

* Update .github/workflows/build.yml

Co-authored-by: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com>

* Update lib/datasource/types.ts

Co-authored-by: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com>

Co-authored-by: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com>

.eslintignore

@@ -16,3 +16,4 @@ coverage
 **/*.generated.ts
 /tools/dist
 /patches
+tmp/

.github/workflows/build.yml

@@ -204,3 +204,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Upload docs
+        uses: actions/upload-artifact@v2.3.0
+        with:
+          name: docs
+          path: tmp/docs

.prettierignore

@@ -18,3 +18,4 @@ bin/yarn*
 **/*.generated.ts
 /tools/dist
 /patches
+**/tmp/

.releaserc

@@ -5,14 +5,21 @@
     [
       "@semantic-release/github",
       {
-        "releasedLabels": false
+        "releasedLabels": false,
+        "assets": [
+          {
+            "path": "tmp/docs.tgz",
+            "label": "docs.tgz"
+          }
+        ]
       }
     ],
     [
       "@semantic-release/exec",
       {
         "verifyConditionsCmd": "run-s verify",
-        "publishCmd": "run-s \"release -- {@}\" -- --release=${nextRelease.version} --sha=${nextRelease.gitHead} --tag=${nextRelease.channel}"
+        "prepareCmd": "run-s \"release:prepare -- {@}\" -- --release=${nextRelease.version} --sha=${nextRelease.gitHead} --tag=${nextRelease.channel}",
+        "publishCmd": "run-s \"release:publish -- {@}\" -- --release=${nextRelease.version} --sha=${nextRelease.gitHead} --tag=${nextRelease.channel}"
       }
     ]
   ],

docs/usage/gitlab-bot-security.md

@@ -1,3 +1,7 @@
+---
+title: GitLab bot security
+---
+
 # GitLab bot security
 
 You should understand GitLab's security model, before deciding to run a "bot" service like Renovate on GitLab, particularly the pipeline credentials.

docs/usage/modules/datasource.md

@@ -1,3 +1,7 @@
+---
+title: Datasources
+---
+
 # Datasources
 
 Once Renovate's manager is done scanning files and extracting dependencies, it will assign a `datasource` to each extracted package file and/or dependency so that Renovate then knows how to search for new versions.

docs/usage/modules/manager.md

@@ -1,3 +1,7 @@
+---
+title: Managers
+---
+
 # Managers
 
 Renovate is based around the concept of "package managers", or "managers" for short.

docs/usage/modules/platform.md

@@ -1,3 +1,7 @@
+---
+title: Platforms
+---
+
 # Renovate Platforms
 
 Renovate aims to be platform-neutral, while also taking advantage of good platform-specific features.

docs/usage/modules/versioning.md

@@ -1,3 +1,7 @@
+---
+title: Versioning
+---
+
 # Versioning
 
 Once Managers have extracted dependencies, and Datasources have located available versions, then Renovate will use a "Versioning" scheme to perform sorting and filtering of results.

docs/usage/templates.md

@@ -15,10 +15,16 @@ Some are configuration options passed through, while others are generated as par
 
 ## Exposed config options
 
+<!-- Autogenerate in https://github.com/renovatebot/renovatebot.github.io -->
+<!-- Autogenerate end -->
+
 <!-- Automatically insert exposed configuration options here -->
 
 ## Other available fields
 
+<!-- Autogenerate in https://github.com/renovatebot/renovatebot.github.io -->
+<!-- Autogenerate end -->
+
 <!-- Insert runtime fields here -->
 
 ## Additional Handlebars helpers

lib/datasource/types.ts

@@ -1,3 +1,5 @@
+import type { ModuleApi } from '../types';
+
 export interface Config {
   datasource?: string;
   depName?: string;
@@ -66,7 +68,7 @@ export interface ReleaseResult {
   replacementVersion?: string;
 }
 
-export interface DatasourceApi {
+export interface DatasourceApi extends ModuleApi {
   id: string;
   getDigest?(config: DigestConfig, newValue?: string): Promise<string | null>;
   getReleases(config: GetReleasesConfig): Promise<ReleaseResult | null>;
@@ -93,4 +95,7 @@ export interface DatasourceApi {
    * false: caching is not performed, or performed within the datasource implementation
    */
   caching?: boolean;
+
+  /** optional URLs to add to docs as references */
+  urls?: string[];
 }

lib/manager/types.ts

@@ -5,7 +5,7 @@ import type {
   ValidationMessage,
 } from '../config/types';
 import type { ProgrammingLanguage } from '../constants';
-import type { RangeStrategy, SkipReason } from '../types';
+import type { ModuleApi, RangeStrategy, SkipReason } from '../types';
 import type { File } from '../util/git/types';
 
 export type Result<T> = T | Promise<T>;
@@ -235,7 +235,7 @@ export interface GlobalManagerConfig {
   npmrcMerge?: boolean;
 }
 
-export interface ManagerApi {
+export interface ManagerApi extends ModuleApi {
   defaultConfig: Record<string, unknown>;
   language?: ProgrammingLanguage;
   supportsLockFileMaintenance?: boolean;

lib/types/base.ts

@@ -0,0 +1,4 @@
+export interface ModuleApi {
+  displayName?: string;
+  url?: string;
+}

lib/types/index.ts

@@ -4,3 +4,4 @@ export * from './versioning';
 export * from './branch-status';
 export * from './vulnerability-alert';
 export * from './pr-state';
+export * from './base';

package.json

@@ -8,7 +8,8 @@
   },
   "scripts": {
     "build": "run-s clean generate:* compile:*",
-    "clean": "rimraf dist",
+    "build:docs": "run-s \"release:prepare {@}\"",
+    "clean": "rimraf dist tmp",
     "clean-cache": "node bin/clean-cache.js",
     "compile:ts": "tsc -p tsconfig.app.json",
     "config-validator": "node -r ts-node/register/transpile-only -- lib/config-validator.ts",
@@ -38,7 +39,8 @@
     "pretest": "run-s generate:* ",
     "prettier": "prettier --check \"**/*.{ts,js,mjs,json,md,yml}\"",
     "prettier-fix": "prettier --write \"**/*.{ts,js,mjs,json,md,yml}\"",
-    "release": "node tools/release.mjs",
+    "release:prepare": "node -r ts-node/register/transpile-only -- tools/generate-docs.ts",
+    "release:publish": "node tools/release.mjs",
     "start": "node -r ts-node/register/transpile-only -- lib/renovate.ts",
     "test": "run-s lint test-schema type-check null-check jest",
     "test-dirty": "git diff --exit-code",

tools/docs/config.ts

@@ -0,0 +1,91 @@
+import table from 'markdown-table';
+import { getOptions } from '../../lib/config/options';
+import { getCliName } from '../../lib/workers/global/config/parse/cli';
+import { getEnvName } from '../../lib/workers/global/config/parse/env';
+import { readFile, updateFile } from '../utils/index';
+
+const options = getOptions();
+
+function genTable(obj: [string, string][], type: string, def: any): string {
+  const data = [['Name', 'Value']];
+  const name = obj[0][1];
+  const ignoredKeys = [
+    'name',
+    'description',
+    'default',
+    'stage',
+    'allowString',
+    'cli',
+    'env',
+    'admin',
+  ];
+  obj.forEach(([key, val]) => {
+    const el = [key, val];
+    if (
+      !ignoredKeys.includes(el[0]) ||
+      (el[0] === 'default' && typeof el[1] !== 'object' && name !== 'prBody')
+    ) {
+      if (type === 'string' && el[0] === 'default') {
+        el[1] = `\`"${el[1]}"\``;
+      }
+      if (type === 'boolean' && el[0] === 'default') {
+        el[1] = `\`${el[1]}\``;
+      }
+      if (type === 'string' && el[0] === 'default' && el[1].length > 200) {
+        el[1] = `[template]`;
+      }
+      data.push(el);
+    }
+  });
+
+  if (type === 'list') {
+    data.push(['default', '`[]`']);
+  }
+  if (type === 'string' && def === undefined) {
+    data.push(['default', '`null`']);
+  }
+  if (type === 'boolean' && def === undefined) {
+    data.push(['default', '`true`']);
+  }
+  if (type === 'boolean' && def === null) {
+    data.push(['default', '`null`']);
+  }
+  return table(data);
+}
+
+export async function generateConfig(dist: string, bot = false): Promise<void> {
+  let configFile = `configuration-options.md`;
+  if (bot) {
+    configFile = `self-hosted-configuration.md`;
+  }
+
+  const configOptionsRaw = (await readFile(`docs/usage/${configFile}`)).split(
+    '\n'
+  );
+
+  options
+    .filter((option) => option.releaseStatus !== 'unpublished')
+    .forEach((option) => {
+      const el: Record<string, any> = { ...option };
+      let headerIndex = configOptionsRaw.indexOf(`## ${option.name}`);
+      if (headerIndex === -1) {
+        headerIndex = configOptionsRaw.indexOf(`### ${option.name}`);
+      }
+      if (bot) {
+        el.cli = getCliName(el);
+        el.env = getEnvName(el);
+        if (el.cli === '') {
+          el.cli = `N/A`;
+        }
+        if (el.env === '') {
+          el.env = 'N/A';
+        }
+      }
+
+      configOptionsRaw[headerIndex] +=
+        `\n${option.description}\n\n` +
+        genTable(Object.entries(el), option.type, option.default);
+    });
+
+  await updateFile(`${dist}/${configFile}`, configOptionsRaw.join('\n'));
+}

tools/docs/datasources.ts

@@ -0,0 +1,36 @@
+import { getDatasources } from '../../lib/datasource';
+import { readFile, updateFile } from '../utils';
+import {
+  formatDescription,
+  formatUrls,
+  getDisplayName,
+  replaceContent,
+} from './utils';
+
+export async function generateDatasources(dist: string): Promise<void> {
+  const dsList = getDatasources();
+  let datasourceContent =
+    '\nSupported values for `datasource` are: ' +
+    [...dsList.keys()].map((v) => `\`${v}\``).join(', ') +
+    '.\n\n';
+  for (const [datasource, definition] of dsList) {
+    const { id, urls, defaultConfig } = definition;
+    const displayName = getDisplayName(datasource, definition);
+    datasourceContent += `\n### ${displayName} Datasource\n\n`;
+    datasourceContent += `**Identifier**: \`${id}\`\n\n`;
+    datasourceContent += formatUrls(urls);
+    datasourceContent += await formatDescription('datasource', datasource);
+
+    if (defaultConfig) {
+      datasourceContent +=
+        '**Default configuration**:\n\n```json\n' +
+        JSON.stringify(defaultConfig, undefined, 2) +
+        '\n```\n';
+    }
+
+    datasourceContent += `\n----\n\n`;
+  }
+  let indexContent = await readFile(`docs/usage/modules/datasource.md`);
+  indexContent = replaceContent(indexContent, datasourceContent);
+  await updateFile(`${dist}/modules/datasource.md`, indexContent);
+}

tools/docs/manager.ts

@@ -0,0 +1,86 @@
+import type { RenovateConfig } from '../../lib/config/types';
+import { getManagers } from '../../lib/manager';
+import { readFile, updateFile } from '../utils';
+import { getDisplayName, getNameWithUrl, replaceContent } from './utils';
+
+function getTitle(manager: string, displayName: string): string {
+  if (manager === 'regex') {
+    return `Custom Manager Support using Regex`;
+  }
+  return `Automated Dependency Updates for ${displayName}`;
+}
+
+function getManagerLink(manager: string): string {
+  return `[\`${manager}\`](${manager}/)`;
+}
+
+export async function generateManagers(dist: string): Promise<void> {
+  const managers = getManagers();
+  const allLanguages: Record<string, string[]> = {};
+  for (const [manager, definition] of managers) {
+    const language = definition.language || 'other';
+    allLanguages[language] = allLanguages[language] || [];
+    allLanguages[language].push(manager);
+    const { defaultConfig } = definition;
+    const { fileMatch } = defaultConfig as RenovateConfig;
+    const displayName = getDisplayName(manager, definition);
+    let md = `---
+title: ${getTitle(manager, displayName)}
+sidebar_label: ${displayName}
+---
+`;
+    if (manager !== 'regex') {
+      const nameWithUrl = getNameWithUrl(manager, definition);
+      md += `Renovate supports updating ${nameWithUrl} dependencies.\n\n`;
+      if (defaultConfig.enabled === false) {
+        md += '## Enabling\n\n';
+        md += `${displayName} functionality is currently in beta testing so you must opt in to test it out. To enable it, add a configuration like this to either your bot config or your \`renovate.json\`:\n\n`;
+        md += '```\n';
+        md += `{\n  "${manager}": {\n    "enabled": true\n  }\n}`;
+        md += '\n```\n\n';
+        md +=
+          'If you encounter any bugs, please [raise a bug report](https://github.com/renovatebot/renovate/issues/new?template=3-Bug_report.md). If you find that it works well, then feedback on that would be welcome too.\n\n';
+      }
+      md += '## File Matching\n\n';
+      if (!Array.isArray(fileMatch) || fileMatch.length === 0) {
+        md += `Because file names for \`${manager}\` cannot be easily determined automatically, Renovate will not attempt to match any \`${manager}\` files by default. `;
+      } else {
+        md += `By default, Renovate will check any files matching `;
+        if (fileMatch.length === 1) {
+          md += `the following regular expression: \`${fileMatch[0]}\`.\n\n`;
+        } else {
+          md += `any of the following regular expressions:\n\n`;
+          md += '```\n';
+          md += fileMatch.join('\n');
+          md += '\n```\n\n';
+        }
+      }
+      md += `For details on how to extend a manager's \`fileMatch\` value, please follow [this link](/modules/manager/#file-matching).\n\n`;
+    }
+
+    const managerReadmeContent = await readFile(
+      `lib/manager/${manager}/readme.md`
+    );
+    if (manager !== 'regex') {
+      md += '\n## Additional Information\n\n';
+    }
+    md += managerReadmeContent + '\n\n';
+
+    await updateFile(`${dist}/modules/manager/${manager}/index.md`, md);
+  }
+  const languages = Object.keys(allLanguages).filter(
+    (language) => language !== 'other'
+  );
+  languages.sort();
+  languages.push('other');
+  let languageText = '\n';
+
+  for (const language of languages) {
+    languageText += `**${language}**: `;
+    languageText += allLanguages[language].map(getManagerLink).join(', ');
+    languageText += '\n\n';
+  }
+  let indexContent = await readFile(`docs/usage/modules/manager.md`);
+  indexContent = replaceContent(indexContent, languageText);
+  await updateFile(`${dist}/modules/manager.md`, indexContent);
+}