paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add techdocs-core plugin to techdocs builder automatically

Browse Source 
Currently users need to modify their mkdocs files to container techdocs-core plugin manually when they want to expose techdocs in Backstage. To have a standardized set of extensions without the need to modify existing files (and possibly pollute alternative/additional mkdocs pipelines) this should be added automatically.

This PR adds a helper function to modify the mkdocs file to contain this plugin if it doesn't exist in the config file.

Co-authored-by: @emmaindal

Signed-off-by: Jussi Hallila <jussi@hallila.com>
This commit is contained in:
Jussi Hallila
2022-02-15 17:01:46 +01:00
parent 5dcf41492f
commit ff0a16fb1a
14 changed files with 286 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/tiny-jobs-hunt.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/techdocs-common': patch
---
Modify techdocs builder to automatically append techdocs-core plugin to mkdocs.yaml file if it is missing. Adds an optional configuration item if this plugin needs to be omitted.
docs/features/techdocs/cli.md
+2
View File
@@ -130,6 +130,8 @@ Options:
if not found.
--etag <ETAG> A unique identifier for the prepared tree e.g. commit SHA. If provided it will be stored
in techdocs_metadata.json.
--omitTechdocsCoreMkdocsPlugin An option to disable automatic addition of techdocs-core plugin to the mkdocs.yaml files.
Defaults to false, which means that the techdocs-core plugin is always added to the mkdocs file.
-v --verbose Enable verbose output. (default: false)
-h, --help display help for command
```
docs/features/techdocs/configuration.md
+5
View File
@@ -37,6 +37,11 @@ techdocs:
pullImage: true
mkdocs:
# (Optional) techdocs.generator.omitTechdocsCoreMkdocsPlugin can be used to disable automatic addition of techdocs-core plugin to the mkdocs.yaml files.
# Defaults to false, which means that the techdocs-core plugin is always added to the mkdocs file.
omitTechdocsCorePlugin: false
# techdocs.builder can be either 'local' or 'external.
# If builder is set to 'local' and you open a TechDocs page, techdocs-backend will try to generate the docs, publish to storage
# and show the generated docs afterwords. This is the "Basic" setup of the TechDocs Architecture.
docs/features/techdocs/creating-and-publishing.md
+3
View File
@@ -79,6 +79,9 @@ plugins:
- techdocs-core
```
> Note - The plugins section above is optional. Backstage automatically adds the `techdocs-core` plugin to the
> mkdocs file if it is missing. This functionality can be turned off with a [configuration option](./configuration.md) in Backstage.
Update your component's entity description by adding the following lines to its
`catalog-info.yaml` in the root of its repository:
packages/techdocs-cli/src/commands/generate/generate.ts
+4
View File
@@ -39,6 +39,7 @@ export default async function generate(cmd: Command) {
const sourceDir = resolve(cmd.sourceDir);
const outputDir = resolve(cmd.outputDir);
const omitTechdocsCorePlugin = cmd.omitTechdocsCoreMkdocsPlugin;
const dockerImage = cmd.dockerImage;
const pullImage = cmd.pull;
@@ -55,6 +56,9 @@ export default async function generate(cmd: Command) {
runIn: cmd.docker ? 'docker' : 'local',
dockerImage,
pullImage,
mkdocs: {
omitTechdocsCorePlugin,
},
},
},
});
packages/techdocs-cli/src/commands/index.ts
+5
View File
@@ -54,6 +54,11 @@ export function registerCommands(program: CommanderStatic) {
'A unique identifier for the prepared tree e.g. commit SHA. If provided it will be stored in techdocs_metadata.json.',
)
.option('-v --verbose', 'Enable verbose output.', false)
.option(
'--omitTechdocsCoreMkdocsPlugin',
"Don't patch MkDocs file automatically with techdocs-core plugin.",
false,
)
.alias('build')
.action(lazy(() => import('./generate/generate').then(m => m.default)));
packages/techdocs-common/src/stages/generate/__fixtures__/mkdocs_with_additional_plugins.yml
+6
View File
@@ -0,0 +1,6 @@
site_name: Test site name
site_description: Test site description
docs_dir: docs/
plugins:
- not-techdocs-core
- also-not-techdocs-core
packages/techdocs-common/src/stages/generate/__fixtures__/mkdocs_with_techdocs_plugin.yml
+5
View File
@@ -0,0 +1,5 @@
site_name: Test site name
site_description: Test site description
# This is a comment that is removed after editing
plugins:
- techdocs-core
packages/techdocs-common/src/stages/generate/__fixtures__/mkdocs_without_plugins.yml
+3
View File
@@ -0,0 +1,3 @@
site_name: Test site name
site_description: Test site description
docs_dir: docs/
packages/techdocs-common/src/stages/generate/helpers.test.ts
+68 -1
View File
@@ -28,10 +28,14 @@ import {
getMkdocsYml,
getRepoUrlFromLocationAnnotation,
patchIndexPreBuild,
patchMkdocsYmlPreBuild,
storeEtagMetadata,
validateMkdocsYaml,
} from './helpers';
import {
patchMkdocsYmlPreBuild,
pathMkdocsYmlWithTechdocsPlugin,
} from './mkDocsPatchers';
import yaml from 'js-yaml';
const mockEntity = {
apiVersion: 'version',
@@ -65,6 +69,15 @@ const mkdocsYmlWithInvalidDocDir2 = fs.readFileSync(
const mkdocsYmlWithComments = fs.readFileSync(
resolvePath(__filename, '../__fixtures__/mkdocs_with_comments.yml'),
);
const mkdocsYmlWithTechdocsPlugins = fs.readFileSync(
resolvePath(__filename, '../__fixtures__/mkdocs_with_techdocs_plugin.yml'),
);
const mkdocsYmlWithoutPlugins = fs.readFileSync(
resolvePath(__filename, '../__fixtures__/mkdocs_without_plugins.yml'),
);
const mkdocsYmlWithAdditionalPlugins = fs.readFileSync(
resolvePath(__filename, '../__fixtures__/mkdocs_with_additional_plugins.yml'),
);
const mockLogger = getVoidLogger();
const warn = jest.spyOn(mockLogger, 'warn');
@@ -289,6 +302,60 @@ describe('helpers', () => {
});
});
describe('pathMkdocsYmlWithTechdocsPlugin', () => {
beforeEach(() => {
mockFs({
'/mkdocs_with_techdocs_plugin.yml': mkdocsYmlWithTechdocsPlugins,
'/mkdocs_without_plugins.yml': mkdocsYmlWithoutPlugins,
'/mkdocs_with_additional_plugins.yml': mkdocsYmlWithAdditionalPlugins,
});
});
it('should not add additional plugins if techdocs exists already in mkdocs file', async () => {
await pathMkdocsYmlWithTechdocsPlugin(
'/mkdocs_with_techdocs_plugin.yml',
mockLogger,
);
const updatedMkdocsYml = await fs.readFile(
'/mkdocs_with_techdocs_plugin.yml',
);
const parsedYml = yaml.load(updatedMkdocsYml.toString()) as {
plugins: string[];
};
expect(parsedYml.plugins).toHaveLength(1);
expect(parsedYml.plugins).toContain('techdocs-core');
});
it("should add the needed plugin if it doesn't exist in mkdocs file", async () => {
await pathMkdocsYmlWithTechdocsPlugin(
'/mkdocs_without_plugins.yml',
mockLogger,
);
const updatedMkdocsYml = await fs.readFile('/mkdocs_without_plugins.yml');
const parsedYml = yaml.load(updatedMkdocsYml.toString()) as {
plugins: string[];
};
expect(parsedYml.plugins).toHaveLength(1);
expect(parsedYml.plugins).toContain('techdocs-core');
});
it('should not override existing plugins', async () => {
await pathMkdocsYmlWithTechdocsPlugin(
'/mkdocs_with_additional_plugins.yml',
mockLogger,
);
const updatedMkdocsYml = await fs.readFile(
'/mkdocs_with_additional_plugins.yml',
);
const parsedYml = yaml.load(updatedMkdocsYml.toString()) as {
plugins: string[];
};
expect(parsedYml.plugins).toHaveLength(3);
expect(parsedYml.plugins).toContain('techdocs-core');
expect(parsedYml.plugins).toContain('not-techdocs-core');
expect(parsedYml.plugins).toContain('also-not-techdocs-core');
});
});
describe('patchIndexPreBuild', () => {
afterEach(() => {
warn.mockClear();
packages/techdocs-common/src/stages/generate/helpers.ts
+1 -96
View File
@@ -125,7 +125,7 @@ class UnknownTag {
constructor(public readonly data: any, public readonly type?: string) {}
}
const MKDOCS_SCHEMA = DEFAULT_SCHEMA.extend([
export const MKDOCS_SCHEMA = DEFAULT_SCHEMA.extend([
new Type('', {
kind: 'scalar',
multi: true,
@@ -203,101 +203,6 @@ export const validateMkdocsYaml = async (
return parsedMkdocsYml.docs_dir;
};
/**
* Update the mkdocs.yml file before TechDocs generator uses it to generate docs site.
*
* List of tasks:
* - Add repo_url or edit_uri if it does not exists
* If mkdocs.yml has a repo_url, the generated docs site gets an Edit button on the pages by default.
* If repo_url is missing in mkdocs.yml, we will use techdocs annotation of the entity to possibly get
* the repository URL.
*
* This function will not throw an error since this is not critical to the whole TechDocs pipeline.
* Instead it will log warnings if there are any errors in reading, parsing or writing YAML.
*
* @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site
* @param logger - A logger instance
* @param parsedLocationAnnotation - Object with location url and type
* @param scmIntegrations - the scmIntegration to do url transformations
*/
export const patchMkdocsYmlPreBuild = async (
mkdocsYmlPath: string,
logger: Logger,
parsedLocationAnnotation: ParsedLocationAnnotation,
scmIntegrations: ScmIntegrationRegistry,
) => {
// We only want to override the mkdocs.yml if it has actually changed. This is relevant if
// used with a 'dir' location on the file system as this would permanently update the file.
let didEdit = false;
let mkdocsYmlFileString;
try {
mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');
} catch (error) {
assertError(error);
logger.warn(
`Could not read MkDocs YAML config file ${mkdocsYmlPath} before running the generator: ${error.message}`,
);
return;
}
let mkdocsYml: any;
try {
mkdocsYml = yaml.load(mkdocsYmlFileString, { schema: MKDOCS_SCHEMA });
// mkdocsYml should be an object type after successful parsing.
// But based on its type definition, it can also be a string or undefined, which we don't want.
if (typeof mkdocsYml === 'string' || typeof mkdocsYml === 'undefined') {
throw new Error('Bad YAML format.');
}
} catch (error) {
assertError(error);
logger.warn(
`Error in parsing YAML at ${mkdocsYmlPath} before running the generator. ${error.message}`,
);
return;
}
// Add edit_uri and/or repo_url to mkdocs.yml if it is missing.
// This will enable the Page edit button generated by MkDocs.
// If the either has been set, keep the original value
if (!('repo_url' in mkdocsYml) && !('edit_uri' in mkdocsYml)) {
const result = getRepoUrlFromLocationAnnotation(
parsedLocationAnnotation,
scmIntegrations,
mkdocsYml.docs_dir,
);
if (result.repo_url || result.edit_uri) {
mkdocsYml.repo_url = result.repo_url;
mkdocsYml.edit_uri = result.edit_uri;
didEdit = true;
logger.info(
`Set ${JSON.stringify(
result,
)}. You can disable this feature by manually setting 'repo_url' or 'edit_uri' according to the MkDocs documentation at https://www.mkdocs.org/user-guide/configuration/#repo_url`,
);
}
}
try {
if (didEdit) {
await fs.writeFile(
mkdocsYmlPath,
yaml.dump(mkdocsYml, { schema: MKDOCS_SCHEMA }),
'utf8',
);
}
} catch (error) {
assertError(error);
logger.warn(
`Could not write to ${mkdocsYmlPath} after updating it before running the generator. ${error.message}`,
);
return;
}
};
/**
* Update docs/index.md file before TechDocs generator uses it to generate docs site,
* falling back to docs/README.md or README.md in case a default docs/index.md
packages/techdocs-common/src/stages/generate/mkDocsPatchers.ts
+166
View File
@@ -0,0 +1,166 @@
/*
* Copyright 2022 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { Logger } from 'winston';
import fs from 'fs-extra';
import yaml from 'js-yaml';
import { ParsedLocationAnnotation } from '../../helpers';
import { getRepoUrlFromLocationAnnotation, MKDOCS_SCHEMA } from './helpers';
import { assertError } from '@backstage/errors';
import { ScmIntegrationRegistry } from '@backstage/integration';
type MkDocsObject = {
plugins?: string[];
docs_dir: string;
repo_url?: string;
edit_uri?: string;
};
const patchMkdocsFile = async (
mkdocsYmlPath: string,
logger: Logger,
updateAction: (mkdocsYml: MkDocsObject) => boolean,
) => {
// We only want to override the mkdocs.yml if it has actually changed. This is relevant if
// used with a 'dir' location on the file system as this would permanently update the file.
let didEdit = false;
let mkdocsYmlFileString;
try {
mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');
} catch (error) {
assertError(error);
logger.warn(
`Could not read MkDocs YAML config file ${mkdocsYmlPath} before running the generator: ${error.message}`,
);
return;
}
let mkdocsYml: any;
try {
mkdocsYml = yaml.load(mkdocsYmlFileString, { schema: MKDOCS_SCHEMA });
// mkdocsYml should be an object type after successful parsing.
// But based on its type definition, it can also be a string or undefined, which we don't want.
if (typeof mkdocsYml === 'string' || typeof mkdocsYml === 'undefined') {
throw new Error('Bad YAML format.');
}
} catch (error) {
assertError(error);
logger.warn(
`Error in parsing YAML at ${mkdocsYmlPath} before running the generator. ${error.message}`,
);
return;
}
didEdit = updateAction(mkdocsYml);
try {
if (didEdit) {
await fs.writeFile(
mkdocsYmlPath,
yaml.dump(mkdocsYml, { schema: MKDOCS_SCHEMA }),
'utf8',
);
}
} catch (error) {
assertError(error);
logger.warn(
`Could not write to ${mkdocsYmlPath} after updating it before running the generator. ${error.message}`,
);
return;
}
};
/**
* Update the mkdocs.yml file before TechDocs generator uses it to generate docs site.
*
* List of tasks:
* - Add repo_url or edit_uri if it does not exists
* If mkdocs.yml has a repo_url, the generated docs site gets an Edit button on the pages by default.
* If repo_url is missing in mkdocs.yml, we will use techdocs annotation of the entity to possibly get
* the repository URL.
*
* This function will not throw an error since this is not critical to the whole TechDocs pipeline.
* Instead it will log warnings if there are any errors in reading, parsing or writing YAML.
*
* @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site
* @param logger - A logger instance
* @param parsedLocationAnnotation - Object with location url and type
* @param scmIntegrations - the scmIntegration to do url transformations
*/
export const patchMkdocsYmlPreBuild = async (
mkdocsYmlPath: string,
logger: Logger,
parsedLocationAnnotation: ParsedLocationAnnotation,
scmIntegrations: ScmIntegrationRegistry,
) => {
await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {
if (!('repo_url' in mkdocsYml) && !('edit_uri' in mkdocsYml)) {
// Add edit_uri and/or repo_url to mkdocs.yml if it is missing.
// This will enable the Page edit button generated by MkDocs.
// If the either has been set, keep the original value
const result = getRepoUrlFromLocationAnnotation(
parsedLocationAnnotation,
scmIntegrations,
mkdocsYml.docs_dir,
);
if (result.repo_url || result.edit_uri) {
mkdocsYml.repo_url = result.repo_url;
mkdocsYml.edit_uri = result.edit_uri;
logger.info(
`Set ${JSON.stringify(
result,
)}. You can disable this feature by manually setting 'repo_url' or 'edit_uri' according to the MkDocs documentation at https://www.mkdocs.org/user-guide/configuration/#repo_url`,
);
return true;
}
}
return false;
});
};
/**
* Update the mkdocs.yml file before TechDocs generator uses it to generate docs site.
*
* List of tasks:
* - Add techdocs-core plugin to mkdocs file if it doesn't exist
*
* This function will not throw an error since this is not critical to the whole TechDocs pipeline.
* Instead it will log warnings if there are any errors in reading, parsing or writing YAML.
*
* @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site
* @param logger - A logger instance
*/
export const pathMkdocsYmlWithTechdocsPlugin = async (
mkdocsYmlPath: string,
logger: Logger,
) => {
await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {
// Modify mkdocs.yaml to contain the needed techdocs-core plugin if it is not there
if (!('plugins' in mkdocsYml)) {
mkdocsYml.plugins = ['techdocs-core'];
return true;
}
if (mkdocsYml.plugins && !mkdocsYml.plugins.includes('techdocs-core')) {
mkdocsYml.plugins.push('techdocs-core');
return true;
}
return false;
});
};
packages/techdocs-common/src/stages/generate/techdocs.ts
+12 -1
View File
@@ -26,11 +26,15 @@ import {
createOrUpdateMetadata,
getMkdocsYml,
patchIndexPreBuild,
patchMkdocsYmlPreBuild,
runCommand,
storeEtagMetadata,
validateMkdocsYaml,
} from './helpers';
import {
patchMkdocsYmlPreBuild,
pathMkdocsYmlWithTechdocsPlugin,
} from './mkDocsPatchers';
import {
GeneratorBase,
GeneratorConfig,
@@ -110,6 +114,10 @@ export class TechdocsGenerator implements GeneratorBase {
await patchIndexPreBuild({ inputDir, logger: childLogger, docsDir });
}
if (!this.options.omitTechdocsCoreMkdocsPlugin) {
await pathMkdocsYmlWithTechdocsPlugin(mkdocsYmlPath, childLogger);
}
// Directories to bind on container
const mountDirs = {
[inputDir]: '/input',
@@ -207,5 +215,8 @@ export function readGeneratorConfig(
'docker',
dockerImage: config.getOptionalString('techdocs.generator.dockerImage'),
pullImage: config.getOptionalBoolean('techdocs.generator.pullImage'),
omitTechdocsCoreMkdocsPlugin: config.getOptionalBoolean(
'techdocs.generator.mkdocs.omitTechdocsCorePlugin',
),
};
}
packages/techdocs-common/src/stages/generate/types.ts
+1
View File
@@ -39,6 +39,7 @@ export type GeneratorConfig = {
runIn: GeneratorRunInType;
dockerImage?: string;
pullImage?: boolean;
omitTechdocsCoreMkdocsPlugin?: boolean;
};
/**