TOAST UI Doc

TOAST UI Doc is a documentation generator used with TOAST UI products that allows you to create documentations for any JavaScript library easily.

🚩 Table of Contents

• What is TOAST UI Doc?
• Main Features
  • API Page
  • Examples Page
  • Search Feature
  • Permalink
  • Customizable Layout Contents
  • Simple Builds
• Demo
• Usage
  • Install
  • Adding Config Files
  • Setting Options in Config Files
  • Running the Command
• Contributing
• License

📑 What is TOAST UI Doc?

TOAST UI Doc is a documentation generator used with TOAST UI products, and is a module that creates a single documentation by combining the API document created by parsing the JSDoc comments with the example page. TOAST UI Doc uses the documentation.js and Gatsby. The layouts TOAST UI Doc is created with Gatsby to be a React component. Simply by configuring the options and running TOAST UI Doc, you can easily create documentations for any JavaScript library.

🎨 Main Features

API Page

TOAST UI Doc parses the JSDoc composed within the JavaScript file to create the API page. The API page can mainly be categorized into seven types, and is represented as a menu in the Local Navigation Bar (LNB).

• MODULES
• EXTERNALS
• CLASSES
• NAMESPACES
• MIXINS
• TYPEDEF

Furthermore, each type has a submenu, and you can easily check the inheritance or mixin relationship, member (property, method) and other custom event API information.

• EXTENDS
• MIXES
• STATIC PROPERTIES
• STATIC METHODS
• INSTANCE METHODS
• EVENTS

Examples Page

TOAST UI Doc reads the HTML file to directly create an Examples page. If you use appropriate selectors for each Example page, you can display HTML and JavaScript snippets within the page. The Try-it-yourself demos and each code snippet are provided as tabs.

Search Feature

You can use the search bar in the top portion of the local navigation bar (LNB) to search for any API and Example pages provided by TOAST UI Doc. TOAST UI Doc also comes with auto-complete feature to facilitate faster transversals between API and Examples pages for users.

Permalink

TOAST UI Doc provides a Github Permalink feature. The permalinks can be found at the top right of each API area, and links the location where the JSDoc file is to the Github repository. Permalinks can be useful when directly accessing the API codes and JSDoc contents for reference.

Customizable Layout Contents

TOAST UI Doc layouts can mainly be categorized in Header, Footer, LNB, Contents (Main, API, and Examples). You can use the config file to readily customize which content goes in Header and Footer areas. Furthermore, if necessary, you can configure whether or not to expose the Examples page.

Simple Builds

TOAST UI Doc comes with Gatsby built into it, so when the build takes place, Gatsby script runs automatically to compile documentation files into a folder. By uploading the created folder onto the Github Pages or onto a server, you can easily create your public API page.

🐾 Demo

• https://nhn.github.io/toast-ui.doc/latest/

🔨 Usage

Install

Use npm to install it globally.

$ npm install -g @toast-ui/doc

Adding Config Files

Add your config files to the root of your working directory. The config file must be in the form of tuidoc.config.json.

project/
├─ ...
├─ package.json
└─ tuidoc.config.json

Setting Options in Config Files

The tuidoc.config.json file can be used to configure following options, and such options can be customized to create more approprite documents. For a full explanation on using options, refer to here.

Configuring the Header Area

[logo] / [text] [version] can be exposed sequentially.

Configuring the Footer Area

A list of product related links including company information can be displayed.

Configuring the Main Page

Configuring the API Page

Configuring the Examples Page

Others

Configuring the Files for Examples Page

In order to display the tabular content in the Examples page, additional configuration is necessary besides managing the options. The page that is finally displayed on the Result tab is the file that has been configured using the examples option, and has to be of HTML format. The code snippets found in JavaScript tab and HTML tab must be declared to be code-js and code-html class, respectively. For the basic template, see here.

...
<div class="code-html">
  <div id="wrapper"></div>
</div>
...
<script type="text/javascript" class="code-js">
  alert('Hello!');
</script>
...

Running the Command

TOAST UI Doc provides a tuidoc CLI, and running the following command will allow you to build your documentation based on the environment settings that you have configured above. First, the Gatsby, wrapped by TOAST UI Doc, is executed, and the --serv flag can be used to preview the created documentation on your local machine.

$ tuidoc --serv

When you are done verifying the local product, running tuidoc command will create two folders, _latest and _[SemVer], under the project root directory. These folders can be used to upload to a server.

$ tuidoc

Or, you can add the commands as scripts to the project's package.json file.

{
  "scripts": {
    "doc:serve": "tuidoc --serv",
    "doc": "tuidoc"
  }
}

🔧 Making a Pull Request

All TOAST UI products are open source. A Pull Request (PR) can be made upon fixing an issue or developing additional features to be implemented.

Install

To install, first fork the master branch to your own personal repository. Then, clone the forked repository to your local machine, and install the following node module. Prior to development, first, make sure that the modules are properly installed.

$ git clone https://github.com/{your-personal-repo}/toast-ui.doc.git
$ cd toast-ui.doc
$ npm install
$ npm run test

Development

Use your local machine for the development process. During the development process, you can use two types of tuidoc scripts, and you can determine which script to use according to your situation.

Running the Dev Server

When the script is run, Gatsby initiates a webpack dev server. You can preview the changes you have made to any react components under src folder in realtime. You can connect to the dev server by going to localhost:8000.

$ npm run tuidoc:dev

Checking the Build Status

When the script is run, Gatsby begins the build as well as the server so that you can check that the created documentation performs properly. In order to check the status of the documentation before distribution, connect to localhost:9000.

$ npm run tuidoc:serve

Pull Request

Finally, perform a final check in order to make sure that there are no problems with your before making a pull request. If none are found, commit, and push it to the repository.

For more detailed explanation on making a PR, refer to the Contributing appendix below.

💬 Contributing

• Code of Conduct
• Contributing guideline
• Issue guideline
• Commit convention

📜 License

This software is provided under MIT License. © NHN Cloud.