labbsr0x/js-to-markdown

Generate code documentation with markdown automatically from js files!

JS-TO-MARKDOWN

A node program to generate markdown automatically from js files. Pull requests and Issues are welcome! 😃 🎉

Table of Contents

• Getting Started
• Running from command line
• Configuration File
• Configuration File Options
• TAGS used to document the JS Code
• Examples
  • Using @CBAll tag
  • Using @CBStart, @CBEnd tags and markdown comments
  • Generating markdown with PropTypes table
• Roadmap

Getting Started

First install js-to-markdown globaly:

npm install js-to-markdown --global

Running from command line

After installing js-to-markdown globaly, you can run it directly from the command line with a variety of useful options.

Here's how to js-to-markdown using js-to-markdown.config.js as a configuration file:

js-to-markdown -c ./js-to-markdown.config.js

Configuration File

Is a JavaScript file

module.exports = {
  input: "../path/to/input/dir",
  output: "../path/to/output/dir",
  subfolders: true,
};

Configuration File Options

Option.	Default	Required	Description
input	none	yes	Path to the input directory to js files
output	none	yes	Path to the output directory where the markdown files will be created
subfolders	true	no	Search js files in subfolders under input directory
outputJsMarkdown	false	no	If true indicates that the output markdown will be writen as a JS file and an index.js file will be created too
propTypesToTable	false	no	If true generates a table with all file propTypes, if any

---

TAGS used to document the JS Code

To help in the JS Code documentation it is possible to add some tags as commentary in your code to generate a more complete markdown output.

All tags must be placed at the beginning of the line as a commentary.

⚠️ If there is no tag in the file, the entire code will be treated as a block of code, the same behavior as if using the @CBAll tag.

The possible tags that can be used are:

@ignore

This tag is used to tell the script to not parse any line of the JS file.

It has to be placed as the first line of the code.

@CBAll

The @CBAll (CB = Code Block) tag indicates that all lines of JS file needs to be parsed inside a markdown code block notation.

@CBStart and @CBEnd

The @CBStart and @CBEnd (CB = Code Block) indicates that all lines between the start and the end tag will be parsed inside a markdown code block notation.

Examples

Using @CBAll tag

React Native Js code example:

//@CBAll
import React from "react";
import { View, Icon, Container, Text } from "react-native";

export default class Welcome extends React.Component {
  showApp = (event) => {
    const { showApp } = this.props;
    event.preventDefault();

    if (showApp) {
      showApp();
    }
  };

  render() {
    return (
      <Container>
        <View style={styles.mainContent}>
          <Icon name="welcome" size={60} customColor={Colors.Yellow} />
          <Text h3 style={styles.title}>
            JS-TO-MARKDOWN
          </Text>
        </View>
      </Container>
    );
  }
}

This code generates the Welcome.md file at output directory defined in the configuration file with:

import React from \'react\';
import { View, Icon, Container, Text } from \'react-native\';
export default class Welcome extends React.Component {
  showApp = (event) => {
    const { showApp } = this.props;
    event.preventDefault();
    if (showApp) {
      showApp();
    }
  };
  render() {
    return (
      <Container>
        <View style={styles.mainContent}>
          <Icon name=\'welcome\' size={60} customColor={Colors.Yellow} />
          <Text h3 style={styles.title}>
            JS-TO-MARKDOWN
          </Text>
        </View>
      </Container>
    );
  }
}

---

Using @CBStart, @CBEnd tags and markdown comments

React Native Js code example:

import React from "react";
import { View, Icon, Container, Text } from "react-native";

//# This is the Welcome file
//Exemple code of how to markdown your JS code
//---
export default class Welcome extends React.Component {
  //## Function to be called when the aplication starts
  //@CBStart
  showApp = (event) => {
    const { showApp } = this.props;
    event.preventDefault();

    if (showApp) {
      showApp();
    }
  };
  //@CBEnd

  //---
  //## Render Method
  render() {
    //@CBStart
    return (
      <Container>
        <View style={styles.mainContent}>
          <Icon name="welcome" size={60} customColor={Colors.Yellow} />
          <Text h3 style={styles.title}>
            JS-TO-MARKDOWN
          </Text>
        </View>
      </Container>
    );
    //@CBEnd
  }
}

This code generates the Welcome.md file at output directory defined in the configuration file with:

This is the Welcome file

Exemple code of how to markdown your JS code

---

Function to be called when the aplication starts

  showApp = (event) => {
    const { showApp } = this.props;
    event.preventDefault();
    if (showApp) {
      showApp();
    }
  };

---

Render Method

    return (
      <Container>
        <View style={styles.mainContent}>
          <Icon name=\'welcome\' size={60} customColor={Colors.Yellow} />
          <Text h3 style={styles.title}>
            JS-TO-MARKDOWN
          </Text>
        </View>
      </Container>
    );

---

Generating markdown with PropTypes table

To enable the parse of PropTypes declarations into a table inside markdown is necessary to mark the propTypesToTable flag inside the configuration file as true

React Native Js code example:

import React from "react";
import PropTypes from "prop-types";
import { View, Icon, Container, Text } from "react-native";

//# This is the Welcome file
//Exemple code of how to markdown your JS code
//---
export default class Welcome extends React.Component {
  //## Function to be called when the aplication starts
  //@CBStart
  showApp = (event) => {
    const { showApp } = this.props;
    event.preventDefault();

    if (showApp) {
      showApp();
    }
  };
  //@CBEnd

  //---
  //## Render Method
  render() {
    //@CBStart
    return (
      <Container>
        <View style={styles.mainContent}>
          <Icon name="welcome" size={60} customColor={Colors.Yellow} />
          <Text h3 style={styles.title}>
            JS-TO-MARKDOWN
          </Text>
        </View>
      </Container>
    );
    //@CBEnd
  }
}

Welcome.defaultProps = {
  showApp: () => {},
  type: "highlight",
  seccondButtonMode: "highlight",
};

Welcome.propTypes = {
  /**
   * Function to be called on app starts
   */
  showApp: PropTypes.func,
  /**
   * This props enable the account to be removed after process
   */
  canRemoveAccount: PropTypes.bool.isRequired,
  /**
   * Indicates how the info will be presented to user
   */
  type: PropTypes.oneOf(["highlight", "opacity", "withoutFeedback"]),
  /**
   * Object with the params to be presented
   */
  params: PropTypes.shape({
    documentType: PropTypes.oneOf(DocumentPreviewScreen.DOCUMENT_TYPES)
      .isRequired,
    buttonMode: PropTypes.oneOf(["highlight", "opacity", "withoutFeedback"])
      .isRequired,
    resource: PropTypes.string.isRequired,
    leftButtonLabel: PropTypes.string,
    leftButtonAction: PropTypes.func,
    internalParams: PropTypes.shape({
      resourceLeftLabel: PropTypes.string.isRequired,
      resourceRightLabel: PropTypes.string,
    }),
    rigthButtonLabel: PropTypes.string,
    rigthButtonAction: PropTypes.func,
  }),
  seccondButtonMode: PropTypes.oneOf([
    "highlight",
    "opacity",
    "withoutFeedback",
  ]),
  documentType: PropTypes.oneOf(DocumentPreviewScreen.DOCUMENT_TYPES),
};

This code generates the Welcome.md file at output directory defined in the configuration file with:

This is the Welcome file

Exemple code of how to markdown your JS code

---

Function to be called when the aplication starts

  showApp = (event) => {
    const { showApp } = this.props;
    event.preventDefault();
    if (showApp) {
      showApp();
    }
  };

---

Render Method

    return (
      <Container>
        <View style={styles.mainContent}>
          <Icon name=\'welcome\' size={60} customColor={Colors.Yellow} />
          <Text h3 style={styles.title}>
            JS-TO-MARKDOWN
          </Text>
        </View>
      </Container>
    );

---

PropTypes

Property	Type	Default	Required	Description
showApp	func	() => {}	false	Function to be called on app starts
canRemoveAccount	bool	none	true	This props enable the account to be removed after process
type	enum	'highlight'	false	One of: [highlight, opacity, withoutFeedback] - Indicates how the info will be presented to user
params	object		false	Object with the params to be presented
params.documentType	enum	none	true	One of: [DocumentPreviewScreen.DOCUMENT_TYPES]
params.buttonMode	enum	none	true	One of: [highlight, opacity, withoutFeedback]
params.resource	string	none	true
params.leftButtonLabel	string	none	false
params.leftButtonAction	func	none	false
params.internalParams	object		false
params.internalParams.resourceLeftLabel	string	none	true
params.internalParams.resourceRightLabel	string	none	false
params.rigthButtonLabel	string	none	false
params.rigthButtonAction	func	none	false
seccondButtonMode	enum	'highlight'	false	One of: [highlight, opacity, withoutFeedback]
documentType	enum	none	false	One of: [DocumentPreviewScreen.DOCUMENT_TYPES]

ROADMAP

• Parse JSDocs tags to markdown;
• Accept other JS extensions (.jsx, .ts, .tsx, ...) to locate and parse files;
• Configuration option to choose if the Markdown file will be saved at output directory or where the original file is;

js-to-markdown's Issues

Configuration File: multiple input values

Configuration File: multiple input values

Problem

Today, we can only provide a single input path, but it can be useful to define more than one source folder.

Feature description

Change input configuration to be possible to define an array with the desired paths, like:

module.exports = {
   input: ["../my-project/app/components", "../my-project/app/util"]
   ...
}

Readme: fix section links

The following README links are not working properly:

• Configuration File
• Using @cball tag
• Using @cbstart, @cbend tags and markdown comments

I've seen that Configuration File has a typo, but the other ones are correct and still not working.
I guess that it is due to '@' symbol.

Add a quick sample usage on README.md

It would be great to have a quick usage sample on README with a JSX small code and the generated markdown output, so people can quickly know how easy it is to use and what to expect.

Roadmap: Option to choose where the Markdown file will be saved

Option to choose where the Markdown file will be saved

Problem

Today, the markdown result file is generated into the output directory indicated at the configuration file.

Feature description

Create a property in the configuration file to indicate that the user wants to save the generate markdown in the same directory as the original JS source code file.

js-to-markdown -c ./js-to-markdown.config.js doen't work

When the config file is in the same path that you're running the command, the file can't be found.

Roadmap: Accept other JS extensions

Accept other JS extensions

Problem

Today, the js-to-markdown only locates and parses JS files with the .js extension. The .js extension is hardcoded inside the getFilesFromInputDirectories function declared in index.js project file.

Feature description

Enable the module to locate and parse other JS files extensions (.jsx, .ts, .tsx, ...).
Maybe it will be necessary to create a new configuration property where the user can indicate one or more file extensions that are necessary to parse.

Roadmap: Parse JSDocs comments to Markdown

Parse JSDocs comments to Markdown

type: Feature

Feature description

JSDocs is an API to generate documentation for JavaScript files, similar to Javadoc.
The API uses predefined tags and comments to document things like modules, namespaces, classes, methods, method parameters, and so on.

The idea of this improvement is to parse some of the JSDocs notations to the markdown that will be generated based on the JS source code.