Docs | Auto Docs

Auto Docs

Wat can build automatically build API and doc snippits for any language, platform or library, so long as the content is contained in one or more markdown files.

Instructions

Go to the autodocs.json file in the Wat repo and click the edit pencil.

This JSON file lists the libraries that Wat can build. All you have to do is add a new JSON object in for your library.

Here is a complete example for Vorpal, the command-line framwork that Wat was built off of.

"vorpal": {
  "language": "javascript",
  "parser": "markdown",
  "urls": {
    "readme": "https://raw.githubusercontent.com/dthree/vorpal/master/README.md",
    "api": {
      "vorpal": "https://raw.githubusercontent.com/wiki/dthree/vorpal/API-|-vorpal.md",
      "catch": "https://raw.githubusercontent.com/wiki/dthree/vorpal/API-|-vorpal.catch.md",
      "command": "https://raw.githubusercontent.com/wiki/dthree/vorpal/API-|-vorpal.command.md",
      "mode": "https://raw.githubusercontent.com/wiki/dthree/vorpal/API-|-vorpal.mode.md",
      "ui": "https://raw.githubusercontent.com/wiki/dthree/vorpal/API-|-vorpal.ui.md",
      "commandInstance": "https://raw.githubusercontent.com/wiki/dthree/vorpal/API-|-CommandInstance.md",
      "events": "https://raw.githubusercontent.com/wiki/dthree/vorpal/Events.md"
    },
    "wiki": {
      "creating-extensions": "https://raw.githubusercontent.com/wiki/dthree/vorpal/Creating-Extensions.md",
      "faq": "https://raw.githubusercontent.com/wiki/dthree/vorpal/FAQ.md"
    }
  }
}

Library name

Pick a clear and succinct name for your library, with the following in mind:

• Should ideally match the project's name
• Must be all-lowercase, regardless of the project's regular casing. Think slug.
• If the library's name is too general or has duplicates, prefix it with its platform. i.e. for mkdirp, use npm-mkdirp.

Insert a new object into the JSON with the name you picked. Please file it alphabetically based on the project name to prevent duplicates.

language

This is the language of the project.

currently supported languages:

• javascript

parser

This is the name of the auto doc generator used to build the library.

currently supported parsers:

• markdown

aliases

An array of other names the project is known by. This is used by the auto-doc parser in correctly building document sets. For example, if the project name is npm-mkdirp, it should include aliases: ["mkdirp"].

urls

This is the list of URLs that Wat will automatically download in order to generate the doc set. For example, for Vorpal above, it includes the README.md of the repo, and all of its wiki pages.

All of these URLs will be downloaded and then searched through for API commands. Additionally, Wat will create a traversable "file structure" based on the names provided in the urls object.

The above Vorpal object will create the following document tree in Wat:

readme/
api/
  vorpal
  catch
  command
  mode
  ui
  commandInstance
  events
wiki/
  creating-extensions
  faq

Where to find markdown files

Remember, you need to link to the raw markdown file, not a Github page that displays it. Here are some common locations of markdown files.

Github Readmes: https://raw.githubusercontent.com/{user}/{repo}/master/README.md Github Wiki: https://raw.githubusercontent.com/wiki/{user}/{repo}/{pagename}.md

Sometimes you just have to look around. For example, Node keeps their markdown source in the ./doc/api dir of their Github repo.

Pull Request

Once you've saved the content, submit a pull request!

Show off your docs

If you've added your own project, show it off by copying the badge below into your README.md.

[![Wat: Documented](https://img.shields.io/badge/wat-documented-blue.svg)](https://github.com/dthree/wat)