feat(documentation): Fixed api doc generation, added doc for dropdown component and fixed small bug

Author: fragsalat

build/paths.js

@@ -8,7 +8,7 @@ module.exports = {
   css: appRoot + '**/*.scss',
   output: outputRoot,
   doc: './doc',
-  docsOutput: outputRoot.concat('docs/api/'),
+  apiDoc: './doc/api',
   e2eSpecsSrc: 'test/e2e/src/*.js',
   e2eSpecsDist: 'test/e2e/dist/'
 };

build/tasks/docs.js

@@ -6,45 +6,56 @@ const glob = require('glob');
 const del = require('del');
 const vinylPaths = require('vinyl-paths');
 const docjs = require('documentation');
+const REGEX_FILE_NAME = /((\w)+(-)*(\w))+(?=.js)/g;
 
+function createDocForFile(filename) {
+  const splittedName = filename.split('/');
+  const filenameWithoutExt = filename.match(REGEX_FILE_NAME)[0];
 
+  return docjs.build([filename], {shallow: true})
+    .then(result => docjs.formats.md(result, {}))
+    .then(output => ({
+      file: filenameWithoutExt,
+      // get the parent folder of file
+      folder: filenameWithoutExt !== 'index' ? splittedName[splittedName.length - 2] : 'index',
+      markdown: output
+    }));
+}
 
 // deletes all files in the output path
 gulp.task('clean-docs', () =>
   gulp.src([`${paths.docsOutput}`])
     .pipe(vinylPaths(del))
 );
 
-gulp.task('build-jsdoc-to-md', () => {
-  const files = glob.sync(paths.source); // glob allows pattern matching for filenames
-  const regexFileName = /((\w)+(\-)*(\w))+(?=.js)/g;
-  const createdMdDocs = [];
-  files
-  .filter(filename => {
-    const name = filename.match(regexFileName)[0];
-    return name !== 'imports';
-  })
-  .map(filename => {
-    const splittedName = filename.split('/');
-    const filenameWithoutExt = filename.match(regexFileName)[0];
-    const jsDocObj = docjs.buildSync([filename], {shallow: true});
-    return docjs.formats.md(jsDocObj, {}, (err, output) => {
-      createdMdDocs.push({
-        file: filenameWithoutExt,
-        folder: filenameWithoutExt !== 'index' ? splittedName[splittedName.length - 2] : '',  // get the parent folder of file
-        markdown: output
-      });
-    });
-  });
-  const writeMdFiles = createdMdDocs.map(mdDoc => {
-    const folder = `${paths.docsOutput}${mdDoc.folder}`;
-    const filePath = mdDoc.file !== 'index' ? `${paths.docsOutput}${mdDoc.folder}/${mdDoc.file}.md` : `${paths.docsOutput}${mdDoc.file}.md`;
-    if (!fs.existsSync(folder)) {
-      fs.mkdirSync(folder);
-    }
-    return fs.writeFile(filePath, mdDoc.markdown);
-  });
-  return Promise.all(writeMdFiles);
+gulp.task('build-jsdoc-to-md', done => {
+  Promise.resolve(glob.sync(paths.source))
+    // Filter file names to match tag name pattern
+    .then(fileNames => fileNames.filter(fileName => {
+      const name = fileName.match(REGEX_FILE_NAME)[0];
+      return name !== 'imports';
+    }))
+    // Generate markdown for each file
+    .then(fileNames =>
+      Promise.all(fileNames.map(createDocForFile))
+    )
+    // Group the markdown docs by there folder
+    .then(docs => docs.reduce((groups, doc) => {
+      groups[doc.folder] = groups[doc.folder] || [];
+      groups[doc.folder].push(doc);
+      return groups;
+    }, {}))
+    // Create markdown files for each folder
+    .then(groups => Object.keys(groups).forEach(folderName => {
+      const group = groups[folderName];
+      const fileName = `${paths.apiDoc}/${folderName}.md`;
+      const content = `# ${folderName}\n${group.map(doc => doc.markdown).join('\n')}`;
+      if (!fs.existsSync(paths.apiDoc)) {
+        fs.mkdirSync(paths.apiDoc);
+      }
+      fs.writeFileSync(fileName, content);
+    }))
+    .then(done);
 });
 
 gulp.task('generate-docs', done => runSequence('clean-docs', 'build-jsdoc-to-md', done));

build/tasks/lint.js

@@ -1,9 +1,25 @@
 var gulp = require('gulp');
 var paths = require('../paths');
 var eslint = require('gulp-eslint');
+const glob = require('glob');
+const docjs = require('documentation');
+const REGEX_FILE_NAME = /((\w)+(-)*(\w))+(?=.js)/g;
 
 // runs eslint on all .js files
 gulp.task('lint', function() {
+  Promise.resolve(glob.sync(paths.source))
+    // Filter file names to match tag name pattern
+    .then(fileNames => fileNames.filter(fileName => {
+      const name = fileName.match(REGEX_FILE_NAME)[0];
+      return name !== 'imports';
+    }))
+    // Generate markdown for each file
+    .then(fileNames => fileNames.forEach(fileName =>
+      docjs.lint(fileName, {}).then(lintOutput => {
+        console.log(lintOutput);
+      })
+    ));
+
   return gulp.src(paths.source)
     .pipe(eslint())
     .pipe(eslint.format())

circle.yml

@@ -43,8 +43,8 @@ deployment:
   release:
     branch: [master, release]
     commands:
-      - gulp prepare-release
-      - git add package.json doc/CHANGELOG.md dist
+      - gulp generate-docs bump-version changelog
+      - git add package.json doc dist
       - git commit -m "Bumped version to $(jq -r .version package.json) [skip ci]"
       - git tag -f -a $(jq -r .version package.json) -m "Automatic release via CircleCI"
       - git push origin $CIRCLE_BRANCH

doc/api/index.md

@@ -0,0 +1,16 @@
+# index
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## WHStyleguide
+
+Our Wholesale-Styleguide Component documentation
+This is our Startpage for our component API
+based on jsDocs
+Here we should add more descriptions
+Below are all components referenced
+
+-   See [WSHeader](ws-header.md)
+-   See [WSDatePicker](ws-date-picker.md)
+-   See [WSDropdown](ws-dropdown.md)
+-   See [WSNotification](ws-notification.md)
+-   See [WSWeekPicker](ws-week-picker.md)

doc/api/ws-date-picker.md

@@ -0,0 +1,64 @@
+# ws-date-picker
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## WSDatePicker
+
+**Extends Component**
+
+Renders a date picker component which is based on flatpickr.
+Possible properties to set are the value as formatted string or Date object.
+To specify a date format pls have a look at the flatpickr formatting rules.
+You can set additional options to the flatpickr by passing the options property.
+If you only want to display an icon instead of a input set prop iconOnly.
+
+**Parameters**
+
+-   `props`  
+
+### constructor
+
+**Parameters**
+
+-   `props` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** React properties
+
+### componentDidMount
+
+Initialize the flatpickr with given options and prevent default change event
+
+Returns **void** 
+
+### componentWillReceiveProps
+
+Update flatpickr when prop's changed
+
+**Parameters**
+
+-   `props` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** React props
+
+Returns **void** 
+
+### componentWillUnmount
+
+Destroy the flatpickr and all events and bindings
+
+Returns **void** 
+
+### onChange
+
+Handle date selections and propagate the value via an custom change event and onChange callback
+
+**Parameters**
+
+-   `selectedDate` **[Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)** The currently selected date
+    -   `selectedDate.0`  
+-   `value` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The date as string using the in props specified formatting
+
+Returns **void** 
+
+### render
+
+Render the component
+
+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**