thesephist / litterate

Generate beautiful literate programming-style description of your code from comment annotations

litterate

Litterate is a command line tool to generate beautiful literate programming-style description of your code from comment annotations.

Check out Litterate's own source code, annotated with litterate, on GitHub Pages.

Usage

If you have npx, you can run litterate on your project by just running

npx litterate

which will run Litterate with the default configuration, found in ./src/defaults.js.

You can also install litterate as a command line tool using npm install --global litterate.

By default, Litterate will count comment blocks starting with //> on a newline as annotation blocks (see files under ./src/ for examples). This means Litterate works by default for C-style comment languages (JavaScript, Java, C[++], Rust's normal comments). Litterate can be configured to work with pretty much any language that has beginning-of-line comment delimiters, like # in Python or ; in a variety of other languages.

You can customize Litterate's output with command line arguments (run litterate --help to see options), or with a configuration file, which you can pass to litterate with the --config command line option.

Usage with npm scripts

Generally, you'll want to have a configuration you use for your project, and a simple way to run Litterate. For this, one option is to have an npm script that runs Litterate with a configuration file in your project. For example, we may have an npm script:

    ...
    "scripts": {
        "docs": "litterate --config litterate.config.js",
    },
    ...

With this script, running npm run docs or yarn docs will run Litterate from your NPM dependencies, with the config file you specified. If you use Litterate this way, there's no need to install Litterate globally; just make sure Litterate is installed for your project as a dependency or devDependency.

Configuration options

Save your configuration in a file, say litterate.config.js, and call Litterate with the config with litterate --config litterate.config.js. An example configuration file (the one Litterate uses for itself) is in the repo, at ./litterate.config.js.

name

Name of your project, which shows up as the header and title of the generated documentation site.

description

Description text for your project, shown in the generated site. You can use full Markdown in the description. Litterate uses marked to parse Markdown.

files

An array of file paths to annotate. You can specify file paths as full paths or glob patterns. On the main page of the generated site, links to individual files will show up in the order they're listed here.

By default, Litterate annotates all files that match ./src/**/*.js.

wrap

If 0, long lines of source code will never be wrapped. If any other number, Litterate will wrap long lines to the given number of characters per line.

baseURL

By default, the generated website assumes the root URL of the site is '/', but for GitHub Pages and other sites, you may want to set a different base URL for the site. This allows you to set a different site base URL.

verbose

Verbose output while Litterate runs, useful for debugging.

output

Specify a different destination directory for the generated docs site. By default, Litterate writes to ./docs/.

annotationStartMark and annotationContinueMark

By default, Litterate only counts comment blocks that look like this, as annotation blocks.

//> Start of annotation block
//  continued annotation block
function add(a, b) {
    // comment that isn't counted
    return a + b;
}

This allows you to write // TODO comments and other logistical comments without having them be parsed into Litterate annotations. If you'd rather use a different prefix to mark the start and subsequent lines of Litterate anotation blocks, you can override annotationStartMark (defaults to //>) and annotationContinueMark (defaults to //).

If you wanted to count all comments, for example, you could override annotationStartMark to //.

Contributing

• yarn install to install dependencies (npm should work for these commands too, but the project prefers Yarn and we use a Yarn lockfile.)

• yarn docs to run Litterate on itself, with the configuration file in the repo. Note that this generates pages with the baseURL set to /litterate, for GitHub pages. Run it with --baseURL / to use the default root URL.

litterate's Issues

Ability to test outputs against a suite of input/output test pairs

This is a bit tricky, since the CLI currently interfaces with the filesystem directly. There's a couple approaches I can think of right now;

1. Refactor the CLI into the filesystem interfacing layer, and the rest of the CLI, so we can mock the files we want to test without having to write or read anything to/from disk. This would also make the whole codebase more modular, but would have performance implications (calls to the FS-interfacing layer for files, and calls for it to write files) and raise some race conditions.
2. The test suite can write files to disk, run the CLI against fully mocked-out directories, and compare the files against their expected results. This would make the testing code more complex, but we'd be able to test the CLI end to end with no refactor.

I'm leaning towards (2), which means this might be pretty time consuming. Probably a mid-term goal to work on.

Consistent error handling, especially around filesystem errors

The codebase as it stands today has a tendency to check for the presence of a file once (usually with glob, then pretty much assume the file is going to be there forever. This is a bad assumption.

When these kinds of assumptions are broken, node's fs module filesystem calls returns a non-null Error object in the callbacks, but we don't really handle errors elegantly right now, and we don't try to recover at all.

Since this is a CLI, when we encounter errors, we should be more descriptive about what error occurred, why it might have happened, and how it could be handled. One solution might be to have a separate errorHandler.js or some similar module to centrally define how errors are presented to the user.

Ability to use custom templates

We have a pretty generic templating system right now -- we just pull in files with {{curlyBrace}} variables in them, and populate it with results. We also have a single stylesheet (templates/main.css) which would be pretty easy to override with a custom one.

The hard part of this is to expose a good API for providing custom templates that doesn't require the user to have to know the inner workings of litterate. Ideally, they should be able to provide 3 files: index.html, source.html, and main.css, and some curlybraced placeholders in the template HTML for where source code lines should go.

A good starting point for this issue would be to allow the user to specify a custom main.css, which wouldn't be very complex.

Another way to make this easier would be to require that templates just be modified versions of the stock templates. This way, pages can be assumed to have the default layout and structure, which should make the overall styling of the code+annotation part of the page a non-issue. In this case, we should outline what parts of the default templates under ./templates/ can be modified, and how much.

Use async (filesystem) calls wherever possible

In the first release, we were focused on getting the minimum functionality, so the current codebase uses a lot of unnecessarily synchronous filesystem access functions (fs.readFileSync, mkdirp.sync, etc.), which isn't great for larger projects, since each of those calls block the entire program.

An example of this is in src/index.js, where we call glob.sync where the asynchronous version should work just fine.

It would be great to switch these over to asynchronous calls wherever it makes sense. One exception is where we initially read the template files at the top of generate.js, which I think is fine, since it's only 3 files regardless of the size of the input.