@instructure/ui-docs-plugin

    8.1.0 • Public • Published

    category: packages

    ui-docs-plugin

    npm  build-status  MIT License  Code of Conduct

    A webpack plugin to generate documentation made by Instructure Inc.

    Installation

    yarn add --dev @instructure/ui-docs-plugin

    Usage

    Set up a new webpack config for your documentation app, and add the plugin:

    // webpack.docs.config.js
    const pkg = require('./package.json')
    
    const DocsPlugin = require('@instructure/ui-docs-plugin')
    
    module.exports = {
      entry: {
        common: ['react', 'react-dom'],
        'my-library': ['src'],
        globals: './globals'
      },
      plugins: [
        new DocsPlugin({
          // absolute path for resolving webpack requires (should be where you're running webpack)
          context: __dirname,
          // search path for documentation files (needs to be an absolute path)
          projectRoot: __dirname,
          // html document title
          title: `${pkg.name} : ${pkg.description} (${pkg.version})`,
          // optional favicon image (path should be absolute or relative to context)
          favicon: 'logo.png',
          library: {
            name: pkg.name,
            version: pkg.version,
            repository: pkg.repository.url, // optional
            author: pkg.author // optional
          },
          // paths should be absolute or relative to projectRoot
          files: ['src/components/*/index.js', 'docs/*.md'],
          ignore: [
            // optional
            '**/node_modules/**',
            '**/__tests__/**'
          ],
          // optional html template (path should be absolute or relative to context)
          template: 'index.ejs'
        })
      ]
    }

    Globals/Code examples

    React and ReactDOM are both in scope for use in code examples, and a render function is also provided if you want to be able to control what is rendered (see below).

    Anything else that you would like to be available in scope, you can define in one of your entries (e.g. ./globals in the example above) like:

    // globals.js
    import * as MyLibrary from './index'
    
    // Make all of the library exports global so we can use them in code examples
    Object.keys(MyLibrary).forEach((key) => {
      global[key] = MyLibrary[key]
    })

    Themes

    The plugin will generate documentation for themes that are compatible with @instructure/emotion. You can make your own theme or import one from @instructure/ui-themes and then add them to the plugin options:

    // webpack.docs.config.js
    
    new DocsPlugin({
      themes: ['src/themes/*/index.js']
    })

    Codepen links

    To display a link to open examples in codepen, add the codepen API data to the plugin options:

    // webpack.docs.config.js
    
    new DocsPlugin({
      library: {
        codepen: {
          // codepen button form data (https://blog.codepen.io/documentation/api/prefill/)
          js_external: [
            // usually whatever webpack entries you've defined for the documentation
            `${pkg.homepage}common.js`,
            `${pkg.homepage}instructure-ui.js`,
            `${pkg.homepage}globals.js`
          ].join(';')
        }
      }
    })

    Documenting a mono-repo

    If you need to document multiple packages in the same repo, configure the library as follows:

    // webpack.docs.config.js
    
    new DocsPlugin({
      library: {
        ...
        packages: 'packages', // relative path (from project root) to the packages directory
        scope: '@instructure' // optional
      }
    })

    Customizing generated paths and IDS

    You can add custom functions to the plugin config to change how document identifiers, titles and paths to JS modules are generated:

    // docs.config.js (in the directory where you're running webpack)
    
    module.exports = {
      ...
      document: {
        identifier: function (docData, context) { // a unique identifier for the document
          ...
        },
        title: function (docData, context) { // title for the document
          ...
        },
        srcPath: function (docPath, context) { // the path to src that will display in the documentation
          ...
        },
        srcUrl: function (docPath, context) { // the href that links to the src
          ...
        },
        requirePath: function (docPath, context) { // the path that displays for the 'commonJS' example in the 'Usage' section
          ...
        },
        esPath: function (docPath, context) { // the path that displays for the 'ES Modules' example in the 'Usage' section
          ...
        }
      }
    }

    Writing documentation

    You can write documentation in markdown files or in code comment blocks in your source files.

    Documentation meta data:

    You can configure optional meta data about a document with YAML front matter inside your markdown content.

    ---
    example: false
    ---
    ---
    category: guides/contributing
    id: code_of_conduct
    order: 3
    title: Code of Conduct
    ---

    The front matter must be the first content in the markdown file or comment block.

    Note: categories can be nested via the / delimiter.

    README files

    In README files you can add the meta data:

    ---
    example: false
    ---
    ---
    describes: MyComponent
    ---

    To have the README file content serve as the description for the resource with the id 'MyComponent'. Usually this will be the index.js file in that directory.

    Documents with the describes meta data won't show up in the documentation navigation.

    Code examples

    If you would like to display an example of a rendered component along with the code example, you can include a markdown code block like:

    ```js
    ---
    example: true
    ---
    <Button>Click Me</Button>
    ```

    If you would like to display the component on a dark background or dark checkerboard, you can add some extra data as yaml front matter to your code block:

    ```js
    ---
    example: true
    background: 'checkerboard-inverse'
    ---
    <Button color="primary" withBackground={false}>Click Me</Button>
    ```

    If you would like to show a more complex code example, you can control what's rendered yourself with the following configuration:

    ```js
    ---
    render: false
    example: true
    ---
    const MyButton = () => <Button>Click Me</Button>
    render(MyButton)
    ```

    To make the code editor read-only you can configure the code block as:

    ```js
    ---
    readOnly: true
    ---
    <Button>Click Me</Button>
    ```

    Development

    From the root of the instructure-ui repo:

    1. Run yarn build:watch
    2. Run yarn dev
    3. Open http://localhost:8080/ in your browser

    Keywords

    none

    Install

    npm i @instructure/ui-docs-plugin

    DownloadsWeekly Downloads

    1,159

    Version

    8.1.0

    License

    MIT

    Unpacked Size

    99.1 kB

    Total Files

    33

    Last publish

    Collaborators

    • kyler-instructure
    • jonscheiding
    • instuici
    • codequistador
    • natearmstrong
    • eschiebel
    • maths22
    • hyan
    • jcrystal
    • skacsmark
    • itadmins
    • quizzesuici
    • instructure-toolsmiths-service-user
    • prenner
    • aogata-inst
    • acallejas
    • viktor.ohad
    • eszter.szabo
    • amireh-inst
    • daniel.hatas.instructure
    • brianlwatson
    • instout