add build & runtime debug logging

README.md

@@ -41,7 +41,7 @@ Create MDX files showcasing your code and Docz turns them into a live-reloading,
 
 Documenting code is one of the most important and time-heavy processes when developing software.
 
-A lot of time is spent on building and maintaining custom documentation sites. 
+A lot of time is spent on building and maintaining custom documentation sites.
 
 Docz enables you to quickly create live-reloading, seo-friendly, production-ready documentation sites with MDX and customize the look, feel and behavior when required by leveraging [GatsbyJS](https://www.gatsbyjs.org) and [Gatsby theme shadowing](https://www.gatsbyjs.org/docs/themes/shadowing/).
 
@@ -121,17 +121,23 @@ yarn docz dev
 
 This will start a local development server and open your documentation site in the browser.
 
-## Build 
+## Build
 
 `yarn docz build` will generate a static site for your site in `.docz/dist/`.
 
-You can try it out with `yarn docz serve` or by serving the generated site with your favorite static file server (e.g. `npx serve .docz/dist`). 
+You can try it out with `yarn docz serve` or by serving the generated site with your favorite static file server (e.g. `npx serve .docz/dist`).
 
-You can have `yarn docz build` emit to a different directory by providing a path to the `dest` field in your doczrc.js or from the command line : `yarn docz build --dest docs-site-directory`. 
+You can have `yarn docz build` emit to a different directory by providing a path to the `dest` field in your doczrc.js or from the command line : `yarn docz build --dest docs-site-directory`.
+
+### Debug
+
+You can render debug information about which files are being parsed by setting the `DEBUG` environment variable to `docz*`.
+
+For example: `DEBUG=docz* yarn docz build`
 
 ## Deploy
 
-The output of docz consists of static assets only. This allows you to deploy your generated `docz` site with any static site hosting provider you'd like. 
+The output of docz consists of static assets only. This allows you to deploy your generated `docz` site with any static site hosting provider you'd like.
 
 Start by building your site with `yarn docz build`, if you haven't provided a `dest` flag to your config then you will find your generated files in `.docz/dist` to copy to the server.
 
@@ -195,4 +201,4 @@ You can also contribute money to help secure docz's future.
   <a href="https://opencollective.com/docz" target="_blank">
     <img src="https://cdn-std.dprcdn.net/files/acc_649651/Q5nVhT" height="80" alt="Open Collective">
   </a>
-</p>
+</p>

core/docz-core/src/lib/Entries.ts

@@ -4,12 +4,14 @@ import { parseMdx } from 'docz-utils/lib/mdast'
 import { isRegExp, isString } from 'lodash/fp'
 import minimatch from 'minimatch'
 import glob from 'fast-glob'
-
+import Debug from 'debug'
 import { Entry, EntryObj } from './Entry'
 import { Plugin } from './Plugin'
 import { Config } from '../config/argv'
 import { getRepoEditUrl } from '../utils/repo-info'
 
+const debug = Debug('docz-core')
+
 const mapToObj = (map: Map<any, any>) =>
   Array.from(map.entries()).reduce(
     (obj, [key, value]) => ({ ...obj, [`${key}`]: value }),
@@ -67,6 +69,12 @@ export class Entries {
         baseNameMatch: false,
         caseSensitiveMatch: false,
       })
+
+      debug(
+        `Located ${filesFromPattern.length} documentation documents via ${filePattern}`
+      )
+      debug(filesFromPattern)
+
       initialFiles = [...initialFiles, ...filesFromPattern]
     }
     const files = initialFiles.filter((value: string) => {

core/docz-core/src/states/props.ts

@@ -3,12 +3,15 @@ import chokidar from 'chokidar'
 import fastglob from 'fast-glob'
 import { State, Params } from '../lib/DataServer'
 import { get, propEq } from 'lodash/fp'
+import Debug from 'debug'
 
 import * as paths from '../config/paths'
 import { Config } from '../config/argv'
 import { docgen, unixPath } from '../utils/docgen'
 import { WATCH_IGNORE } from './config'
 
+const debug = Debug('docz-core')
+
 export const getPattern = (config: Config) => {
   const {
     ignore,
@@ -48,8 +51,15 @@ export const initial = (config: Config, pattern: string[]) => async (
 ) => {
   const { filterComponents } = config
   const cwd = paths.getRootDir(config)
+
   const files = await fastglob(pattern, { cwd, caseSensitiveMatch: false })
+  debug(`Located ${files.length} component files via ${pattern.join(', ')}`)
+  debug(files)
+
   const filtered = filterComponents ? filterComponents(files) : files
+  debug(`Component filter returned ${filtered.length} files:`)
+  debug(filtered)
+
   const metadata = await docgen(filtered, config)
   p.setState('props', metadata)
 }

core/docz/package.json

@@ -27,6 +27,7 @@
     "@mdx-js/react": "^1.0.27",
     "array-sort": "^1.0.0",
     "capitalize": "^2.0.0",
+    "debug": "^4.1.1",
     "docz-core": "^2.3.0-alpha.5",
     "fast-deep-equal": "^2.0.1",
     "gatsby": "^2.13.27",

core/docz/src/components/Props.tsx

@@ -4,11 +4,14 @@ import { assoc, first, get, mapValues, kebabCase } from 'lodash/fp'
 import capitalize from 'capitalize'
 import marksy from 'marksy'
 import { pascalCase } from 'pascal-case'
+import Debug from 'debug'
 
 import { doczState } from '../state'
 import { useComponents } from '../hooks'
 import { humanize } from '../utils/humanize-prop'
 
+const debug = Debug('docz')
+
 export interface EnumValue {
   value: string
   computed: boolean
@@ -118,20 +121,28 @@ export const Props: SFC<PropsProps> = ({
   const componentName =
     filemetaName || get('displayName', component) || get('name', component)
 
-  const componentMatcher = (componentName: string, item: any) => {
-    const matchingPatterns = [
-      filename,
-      `/${componentName}.`,
-      `/${kebabCase(componentName)}.`,
-      `/${pascalCase(componentName)}.`,
-    ]
-    return !!matchingPatterns.find(pattern => item.key.includes(pattern))
+  if (!stateProps || stateProps.length === 0) {
+    console.warn(`Looks like no components have been parsed via docz.`)
+    return null
   }
 
-  const found =
-    stateProps &&
-    stateProps.length > 0 &&
-    stateProps.find(item => componentMatcher(componentName, item))
+  const keys: string[] = stateProps.map(item => item.key)
+
+  const matchingPatterns = [
+    filename,
+    `/${componentName}.`,
+    `/${kebabCase(componentName)}.`,
+    `/${pascalCase(componentName)}.`,
+  ]
+
+  debug(`Matching component props via ${matchingPatterns.join(', ')}:`)
+  debug(keys)
+
+  const found = keys.find(key => {
+    return !!matchingPatterns.find(pattern => key.includes(pattern))
+  })
+
+  debug(`Found the following components for ${filename} alias ${componentName}`)
 
   const value = get('value', found) || []
   const firstDefinition = first(value)