# fishfingers

> Documentation Generator

Latest version **0.0.3** (published 2020-02-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install fishfingers
pnpm add fishfingers
yarn add fishfingers
bun add fishfingers
```

Provides the command `fishfingers`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.3 |
| Published | 2020-02-04 |
| First published | 2020-01-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 19 |
| Unpacked size | 44.3 KB |
| Known vulnerabilities | 0 (+6 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Morten Henriksen Birk |
| Maintainers | mortenhbirk |

## Links

- npm: https://www.npmjs.com/package/fishfingers
- Repository: https://github.com/MortenBirk/fishfingers
- Homepage: https://github.com/MortenBirk/fishfingers#readme
- Issues: https://github.com/MortenBirk/fishfingers/issues
- npm.io page: https://npm.io/package/fishfingers

## Dependencies (19)

- [glob](https://npm.io/package/glob.md) ^7.1.6
- [react](https://npm.io/package/react.md) ^16.12.0
- [prismjs](https://npm.io/package/prismjs.md) ^1.18.0
- [webpack](https://npm.io/package/webpack.md) ^4.41.5
- [react-dom](https://npm.io/package/react-dom.md) ^16.12.0
- [css-loader](https://npm.io/package/css-loader.md) ^3.4.1
- [@babel/core](https://npm.io/package/@babel/core.md) ^7.7.7
- [webpack-cli](https://npm.io/package/webpack-cli.md) ^3.3.10
- [babel-loader](https://npm.io/package/babel-loader.md) ^8.0.6
- [style-loader](https://npm.io/package/style-loader.md) ^1.1.2
- [@babel/parser](https://npm.io/package/@babel/parser.md) ^7.7.7
- [@babel/traverse](https://npm.io/package/@babel/traverse.md) ^7.7.4
- [@babel/preset-env](https://npm.io/package/@babel/preset-env.md) ^7.7.7
- [@material-ui/core](https://npm.io/package/@material-ui/core.md) ^4.8.3
- [@material-ui/icons](https://npm.io/package/@material-ui/icons.md) ^4.5.1
- [webpack-dev-server](https://npm.io/package/webpack-dev-server.md) ^3.10.1
- [@babel/preset-react](https://npm.io/package/@babel/preset-react.md) ^7.7.4
- [html-webpack-plugin](https://npm.io/package/html-webpack-plugin.md) ^3.2.0
- [@babel/plugin-proposal-class-properties](https://npm.io/package/@babel/plugin-proposal-class-properties.md) ^7.8.3

## Recent versions

- 0.0.3 (latest) — 2020-02-04
- 0.0.2 — 2020-01-29
- 0.0.1 — 2020-01-28

## README

# What is this

Fishfingers is a very simple (and early stage) documentation generator. It generates a simple and readable documentation from source code comments (currently a very limited subset of [JSDoc](https://github.com/jsdoc/jsdoc))

It supports writing of very simple example files, which will be run directly in the browser, kind of like [Styleguidist](https://github.com/styleguidist/react-styleguidist) but for none ui libraries.

# Installation and setup

First install fishfingers

`npm install --save-dev fishfingers`

Create a fishfingers folder with the 2 config files

```
fishfingers/
  config.js
  imported.js
```

## config.js
The config file defines where the source files are found, and where the documentation should be generated
```js
module.exports = {
  title: 'Some title',
  src: 'sourceCodeFolder/',
  output: 'documentationFolder/'
}
```

## imported.js
This file should basically import everyhing that you are importing in the examples. This is a crude hack for now, and should probably not be needed in later versions. Every import must be relative to the `root` alias, which points to the root of your project.

For instance the file could look like the following.
```js
import { x, y, z } from 'root/someFolder/someFile'
import something from 'root/anotherFile'
```

# Writing documentation
In your source code document elements with block comments.

```js
   /**
    * Functions and class methods can be documented with a description, parameters and return values
    * @param {number} b 
    * @returns {number} The number plus 5
    */
   function someFunc(b) {
    return b + 5
   }
```

```js
 /**
  * Objects can be documented with property types
  */
 const someObject = {
   /** 
    * @type {number}
    * This is the property a 
    * */
   a: 5,
   /** This is the property d */
   d: () => 'lol'
 }
```

## Examples
Examples can be added through markdown files. It is recomended to create examples in separate `.md` files next to the source code being documented

An example is just a markdown file (which currently only uses markdown for editor highlighting). The structure however has to be very strict.

Every example must start with a @id tag which is basically the name of the element to be documented. A title and description should also be added. Finally the example is added. Notice that imports are actually ignored, and must be provided in the `imported.js` config file.

Here is an example of how `someFile.md` could be documented with examples.

```
@id something
@title A good example
@desc This is a very good example
```js
import { something } from './someFile'
const x = something(10)
console.log('This is x ' + x)
```


# Example Gotchas

## This is not real MarkDown
MarkDown files are used since they allow for nice code highlighting in editors, however we currently do not parse actual markdown, and do have very specific requirements for the structure.

## Example id
It is required with an id before every example, not just before a bunch of examples.

*This can be fixed quite fast if needed*

## Imports

Multi line imports or requires will break examples

*This can be fixed quite fast*

Imports and requires are visible in all example files, but will simply be ignored in the actual code.

Instead users can provide the actual imports in the config file, such that the code can run using the imported variables.

This is done to make implementation much easier, since we can look at raw strings, and ignore any advanced parsing.

For now this is not a big problem, since only the library being documented should be imported in simple examples.

*This requires some work to fix, since we have to do proper parsing of the example code*

## No user provided webpack config
There is currently no support for custom webpack configs. Hence examples have to follow the standard of the babel configuration chosen by this project. This also means that examples should probably import previously transpiled library distributions.

---
_Source: https://npm.io/package/fishfingers · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._