Skip to content

Dynamically generated documentation for your domain

License

Notifications You must be signed in to change notification settings

herbsjs/herbsshelf

Repository files navigation

CI build codecov

herbsshelf

Welcome to the shelf!

This is a self-generate documentation, here you can see all the flow of information in the application.

You can use the lateral panel to navigate into Use Cases of this application.

Installing

    $ npm install @herbsjs/herbsshelf

Functioning

To use the shelf you will need to pass a list of usecases to it, it will read them and return a string from an HTML document with the generated documentation.

Using

The quickest way to use the herbs shelf is to create a rest route in your api and expose the documentation generated by the shelf.

Consider a file called _uclist.js with this inside

module.exports = (injection) => {
    return [
        { usecase: require('./myUseCaseFile').myUseCaseName(injection), tags: { group: 'GroupOne' } },
        { usecase: require('./myUseCase2File').myUseCase2Name(injection), tags: { group: 'GroupOne' } },
        { usecase: require('./myUseCase3File').myUseCase3Name(injection), tags: { group: 'GroupTwo' } },
    ]
}

In your app or server file, import the shelf dependecy and the list of usecases

const usecases = require('../../domain/usecases/_uclist')
const renderShelfHTML = require('herbsshelf')

And call the shelf into you prefered rest route

 this.app.get('/herbsshelf', (req, res, next) => {
    res.setHeader('Content-Type', 'text/html')
    const shelf = renderShelfHTML('Project Name', usecases(), entities)
    res.write(shelf)
    res.end()
})

If your project has a readme.md, this content should be shown at the beginning of the project. If you want to use a custom readme, you can specify on startup:

const shelf = renderShelfHTML('Project Name', usecases(), entities, './custom-readme.md')

You can see the full functionality into the TODO-LIST ON HERBS repository

TODO

  • Self-documentation
  • Add templates and injection of css file
  • Entities of gotu support
  • Playground functionality
  • GraphQL documentation sample

Contribute

Come with us to make an awesome herbsshelf.

Now, if you do not have the technical knowledge and also have intended to help us, do not feel shy, click here to open an issue and collaborate their ideas, the contribution may be a criticism or a compliment (why not?)

If you would like to help contribute to this repository, please see CONTRIBUTING

License

herbsshelf is released under the MIT license