justine v0.2.0

Justine

A configurable HTML documentation generator

:rotating_light: Pre-release (just for the brave ones :wink: !) :rotating_light:

There's a large amount of work to be done. Any help is appreciated!

If you wish to see generated documetation examples, visit e2e directory. There you can find subdirectories containing example source files (src) and Justine output (output/docs) together with screens of the generated documentation (output/screens).

Supported languages

• JSDoc

Motivation

I like to document my code right in the file instead of writing detailed README. Unfortunately, I didn't find any mobile-friendly and easy to customize HTML documentation generated from JSDoc (and possibly other docstring languages). You can use one of JSDoc templates, but I had hard times overriding styles and adjusting it, especially when some larger changes were needed. Also, I wished to experiment with some kind of a configuration file (which could be connected to a web configurator in the future maybe :wink: ?) And that's why I'm working on this project.

Features

Configurable

• you can change basic styles with the configuration file described below
• it is very easy to add new configuration options for a developer
• if the configuration available is not enough for you, just take the project, adjust Vue components in lib/template/components and build a completely different output :wink:

Style

• coded with mobile-first approach
• modern and lightweight default style based on Milligram
• stackable parameters tables:

Installation

npm install justine
yarn add justine

You can install Justine globally or locally (but a problem may occur when installing it as a global package with yarn)

CLI

justine <inputPath> [outputPath] [options]

Available options

-p Start a preview server and set the port (defaults to 8080)

-c Configuration file path

Examples

justine ~/project/src

justine ~/project/src ~/project/src/doc -p

justine ~/project/src -p 8000

justine ~/project/src -c ~/some_dir/justine.js

API

const justine = require('justine');

justine(inputPath, outputPath, configPath, preview, port)
  .then(() => {})
  .catch(err => {});

inputPath

• a file or a directory with files containing your source code commented with JSDoc strings
• required

outputPath

• output directory
• optional, generated documentation will be placed to /docs directory created in a current location by default

configPath

• justine.js path
• optional, please see configuration file section below for more information

preview

• preview server will be started when it is true
• optional, default value is false

port

• preview server port
• optional, default value is 8080

Configuration file

You can create justine.js if you wish to customize the documentation style. You should place the file to a directory from which you run Justine or provide its path if you need to place it anywhere else. The file has experimental format right now (more options will be added soon):

module.exports = {
  title: 'My documentation',
  favicon: '<path_to_your_favicon>',
  breakpoint: 900,
  main: {
    backgroundColor: '#fff',
  },
  doclet: {
    header: {
      color: '#545f74',
    },
    subheaders: {
      color: '#f3b195',
    },
    paramsTable: {
      header: {
        backgroundColor: '#9dbada',
        color: '#fff',
      },
    },
  },
};

Requirements

• Node v8.9.4 or newer

Browsers support

TODO

JSDoc tags support

TODO

How you can help

1. Let's code together with me
2. Use Justine and let me know what worked for you and what didn't (bugs, missing support for some JSDoc tags...)
3. Documentation

Notes

How to add support for another language?

I decided to create a universal, simple and tree-like JSON format which can be possibly used as a bridge between any programming language docstrings and Justine.

justine-jsdoc2json converts jsdoc TaffyDB doclets to customized Justine JSON-like input.

So, for example, creating justine-pydoc2json should be the only extra task needed to add Python support.

Developers

You can run the development server inside lib/template directory to immediately see how your updates of Vue.js components affect the generated documentation:

1. yarn install
2. Copy dev/data.example.js to dev/data.js
3. Copy dev/justine.example.js to dev/justine.js
4. yarn dev

You can find the documentation template in lib/template. The development server will be automatically reloaded after updating files in this directory but you need to restart the development server yourself after updating dev/data.js or dev/justine.js.

Testing

yarn unit
yarn e2e

Please see e2e/README.md for e2e tests explanation.