RFC: MKDocs

[pgollucci]

Projen >> Components >> MKDocs

Like other projen things its documentation should be self hosting. This was inspired by
a conversation on cdk.dev Slack between Philip and Elad.

Table of Contents

• Projen >> Components >> MKDocs
  • Table of Contents
    • Problem
    • Use Case
    • Usage
      • .projenrc.js
    • Dependencies and future TODO
    • Assumptions
    • Implementation
      • Build Steps
      • Release Steps
      • Other
      • Types
      • Classes
      • Synthesize
      • docgen

Problem

• Documentation infra setup that can be modeled with higher languages than yaml

Use Case

• projen/projen based on awslabs/cdk8s and then for cdk-constructs/catalog
• $work

Usage

.projenrc.js

const project = new Project({
    ...
    mkDocs: true // @default: false
    ...
});

Dependencies and future TODO

• [cli] Initialize Python application without setup.py aws/aws-cdk#9135
• [WIP] refactor(node-project): meta options need to move to Project #369
• Python
• Pipfile
• Pipenv

Assumptions

• It is ok for Pipfile to install mkdocs and projen will pipenv exec via tasks.exec()

Implementation

• a projen Component
• buildTask will spawn a sub-task with steps
• releaseTask will spawn a sub-task with steps

Build Steps

1. projen build will include
   https://github.com/awslabs/cdk8s/blob/master/docs/build.sh

mkdocs build

Release Steps

1. projen release will include

mkdocs gh-deploy

Other

1. projen mkdocs:serve will forward to

mkdocs serve

mkdocs.ts compontent

import { Component } from './component';
import { Project } from './project';
// import { SampleFile } from './sample-file';
// import { YamlFile } from './yaml';


/**
 * https://www.mkdocs.org/user-guide/configuration/
 * Only site_name as siteName is required
 */

/**
 *
 */
export interface MkDocsThemePalatteProps {

  /**
   *
   */
  readonly scheme: string;

  /**
   *
   */
  readonly primary?: string;

  /**
   *
   */
  readonly accent?: string;
}

export interface MkDocsThemeFontProps {

  /**
   *
   */
  readonly text: string;

  /**
   *
   */
  readonly code: string;
}

export interface MkDocsThemeIconProps {

  /**
   * The Theme Icon Logo
   */
  readonly logo: string;
}

/**
 * An Mkdocs Theme
 * The theme itself is optional but if you define one
 * Some fields are required
 * Projen will define its own theme elsewhere
 */
export interface MkDocsThemeProps {

  /**
   * Name of the theme
   */
  readonly name: string;

  /**
   * Directory containing a custom theme
   * @default
   */
  readonly customDir?: string;

  /**
   * List of files to add to the theme
   * The templates must be located in either
   * the theme's template directory
   * or
   * in the custom_dir defined in the theme configuration.
   * @default []
   */
  readonly staticTemplates?: Array<String>;

  /**
   * Whether to enable `highlightjs`
   * @default false
   */
  readonly highLightJss?: boolean;

  /**
   * 79+ styles(colors) available
   * @default github
   */
  readonly hlJsStyle?: string;

  /**
   * If enabled, for what languages
   * @default []
   */
  readonly hlJsLanguages?: Array<String>;

  /**
   * Language to target
   * @default en
     */
  readonly language?: string;

  /**
     * Palatte
     * @default
     */
  readonly palette?: MkDocsThemePalatteProps;

  /**
     * Features
     * @default
     */
  readonly features?: Array<string>;

  /**
     * @default
     */
  readonly font?: MkDocsThemeFontProps;

  /**
     * @default
     */
  readonly icon?: MkDocsThemeIconProps;

  /**
   * The logo
   * @default
   */
  readonly logo?: string;

  /**
     * @default
     */
  readonly favicon?: string;
}

/**
 * MkDocs Navigation (aka a map of pages)
 * Note, siteUrl can affect the relativity of these
 */
export interface MkDocsNavProps {

  /**
   * List of Mkdocs pages
   * @default index.md
   */
  readonly pages?: Record<string, string>;
}

/**
 *
 */
export interface MkDocsMarkDownExtensionProps {

  /**
   * Name of the extension
   */
  readonly name: string;

  /**
   * Extension specific settings
   * @default:
   */
  readonly flags?: Record<string, string>;
}

/**
 *
 */
export interface MkDocsMarkDownPluginProps {

  /**
   * Name of the plugin
   */
  readonly name: string;

  /**
   * Plugin specific settings
   * @default:
   */
  readonly settings?: Record<string, string | Record<string, string>>;
}

/**
 *
 */
export interface MkDocsExtraProps {

  readonly social: any;
}

/**
 *
 */
export interface MkDocsProps {

  /**
     * The documentation site name
     * This is the only required mkdocs.yml param
     * @default `project.name`
     */
  readonly siteName: string;

  /**
     * The documentation site url
     * @default
     */
  readonly siteUrl?: string;

  /**
     * The repository url
     * @default: parsed from `project.repository` minus .git
     */
  readonly repoUrl?: string;

  /**
     * The repository name
     * @default: parsed from `project.repository`
     */
  readonly repoName?: string;

  /**
     * The Browser URL to edit
     * @default: ""
     */
  readonly editUri?: string;

  /**
     * The documentation site description
     * @default `project.description`
     */
  readonly siteDescription?: string;

  /**
     * The documentation site author
     * @default `project.author`
     */
  readonly siteAuthor?: string;

  /**
     * The documentation site copyright
     * @default: `project.copyright`
     */
  readonly copyright?: string;

  /**
   * @example ['token', 'siteDomain']
   * @example ['UA-27795084-5', 'mkdocs.org']
   * @default []
   */
  readonly googleAnalytics?: Array<String>;

  /**
   * What branch to use when gh-deploy
   * @default "gh-pages"
   */
  readonly remoteBranch?: string;

  /**
   * What remote to use when gh-deploy
   * @default origin
   */
  readonly remoteName?: string;

  /**
     * List of the pages in the `docsDir`
     * @default
     */
  readonly nav?: MkDocsNavProps;

  /**
     * The `mkdocs` theme
     * https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
     * @default
     */
  readonly theme?: MkDocsThemeProps;

  /**
     * The directory to put docs in
     *
     * @default "docs-mk"
     * docs is the default but is shared with docgen for API via typedoc
     * mkdocs is for themes see `MkDocsThemeProps`
     */
  readonly docsDir?: string;

  /**
     * Extensions to load
     *
     */
  readonly markdownExtensions?: MkDocsMarkDownExtensionProps;

  /**
     * Plugins to load
     * https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
     */
  readonly plugins?: MkDocsMarkDownPluginProps;

  /**
     * List of JavaScript Files to embed
     * @default []
     */
  readonly extraJavaScript?: [];

  /**
     * List of CSS Files to embed
     * @default []
     */
  readonly extraCss?: Array<String>;

  /**
     * Extra stuff to embed
     * @default
     */
  readonly extra?: MkDocsExtraProps;
}

/**
 *
 */
export class MkDocs extends Component {

  private config: MkDocsProps;

  /**
   *
   * @param project
   * @param props
   */
  constructor(project: Project, props: MkDocsProps) {
    super(project);

    this.config = {
      ...props,
    };
    if (this.config) {
      let x = 1;
      if (x) {
        x=1;
      }
    }
  }
/*
  public addPage(relPath: string, name?: string): void {
    if (this.config) {
      let extra: number = 1;
      extra=0;
    }
    relPath = name ?? '';
  }
*/
  // plus wrappers for the above props as needed
}

Synthesize

• writes out ./mkdocs.yaml using YamlFile
• mkdir props.docDir if DNE then write out props.docsDir/index.md if using SampleFile
• props.docsDir/!*.js is added to .gitignore
• Pages will be kept in props.docsDir/.pages and included

docgen

• docgen API docs will land in props.docsDir accordingly

[pgollucci]

As a follow up we would then organize the docs or mkdocs dir as

projen/docs
tree .
.
├── cli
├── components
│   ├── github
│   ├── mkdocs.md
│   ├── tasks
│   └── web
├── index.md
└── projects
    ├── awscdk-construct.md
    └── node.md

[pgollucci]

There will be zero python 2 support.

[pgollucci]

https://github.com/awslabs/cdk8s/blob/master/mkdocs.yml
https://github.com/mkdocs/mkdocs/blob/master/mkdocs.yml
https://github.com/peaceiris/mkdocs-material-boilerplate/blob/master/mkdocs-sample.yml
https://github.com/aws/jsii/blob/main/gh-pages/mkdocs.yml
https://www.mkdocs.org/user-guide/configuration

[github-actions]

This issue is now marked as stale because it hasn't seen activity for a while. Add a comment or it will be closed soon.

[eladb]

Keep

[github-actions]

Closing this issue as it hasn't seen activity for a while. Please add a comment @mentioning a maintainer to reopen.

[github-actions]

Closing this issue as it hasn't seen activity for a while. Please add a comment @mentioning a maintainer to reopen.

[github-actions]

This issue is now marked as stale because it hasn't seen activity for a while. Add a comment or it will be closed soon.

[github-actions]

Closing this issue as it hasn't seen activity for a while. Please add a comment @mentioning a maintainer to reopen.