Docstrap

Documentation generator.

Instalation

npm i @rebelstack-io/docstrap -g

Usage

docstrap [ -d | --dir=<path>] [<args>]

if no dir provided will generate documentation webview in docs folder

Configuration file

For better results is recomended to add a configuration file wich contains basic information such name of your project, keywords, views sections and more. This file must be in the route where you execute the docstrap command with the name .docstrap.js.

• example

	'theme': 'default',
	'name': 'Docstrap',
	'description': 'Docstrap is an open-source library, allows you to generate documentation web-view for your projects in a organize and lightweight way',
	'discord': '#linktodiscord',
	'benefits': [
		`<div class="porperty">
			<i class="fas fa-feather-alt"></i>
			<h3>Lightweight</h3>
			<p>
				Docstrap scales well without adding overhead to the application. Generated files ara Plain vanilla HMTL-CSS-JS.
			</p>
		</div>`,
		`<div class="porperty">
			<i class="fas fa-tachometer-alt"></i>
			<h3>Fast</h3>
			<p>
				Docstrap use NodeJS alone, avoiding convoluted frameworks so your documentation can be generated by yourself or CI/CD process in an optimal way.
			</p>
		</div>`
	],
	'links': [
		`<a href="#expressif">
			<img src="img/expressif-boxmodel.jpeg" alt="expressif logo">
		</a>`,
		`<a href="#metaflux">
			<img src="img/metaflux-logo-black.svg" alt="expressif logo">
		</a>`
	],
	'repository': 'https://github.com/rebelstackio/docstrap.git'

this is not mandatory, it will generate the view eather way without a configuration file, you latter can modify your just generated HTML files with the info for your project.

Documentation structure

.
+-- community
|	+-- index.html
+-- css
|	+-- general.css
|	+-- main.css
|	+-- responsive.css
+-- docs
|	+-- api
|	|	+-- api-reference.md
|	|	+-- index.html
|	+-- examples
|	|	+-- examples.md
|	|	+-- index.html
|	+-- faq
|	|	+-- faq.md
|	|	+-- index.html
|	+-- getting-started
|	|	+-- getting-started.md
|	|	+-- index.html
|	+-- overview
|	|	+-- overview.md
|	|	+-- index.html
+-- img
|	+-- default-logo-white.svg
|	+-- default-logo.svg
+-- js
|	+-- index.js
|	+-- markdown.js
+-- index.html

Notice that there are some HTML files with .md files, the idea is to keep writing your documentation as you're used to, we then parse every MD file to the web view, all this is done in the server-side, so your HTML files will be fully statics helping with loading time and SEO, so don't forget to build your docstrap when a change to the .md files, or just leave it to Travis, Jenkins or the CI of your choice.

But what's under the hood? how does it work?

Docstrap is really simple what it does, we have a template already make wich only changes a few parts of the web view, such as project name, description, links for repositories or related contend.

It uses fs-extra to cp how the bash command cp -R would do, the template is copied to a directory you provide or docs/ folder for default.

All the HTML files in the template have those configuration variables with the convection {{varName}}, as long a variable in the config file has the same name as the ones in the HTML will replace it for the variable value, so we can map how many variables to the template we want.

• variable example in the template

<title>{{name}}</title>

• variable in the config file

..., 'name': 'Docstrap', ...

that is made by this util function

function parseConfigToHTML(htmlSTR, config) {
	const varMatch = htmlSTR.match(new RegExp('(?<=\{\{).+?(?=\}\})','g'));
	let resp = htmlSTR;
	varMatch.forEach((_v) => {
		let value = config[_v];
		resp = resp.replace(new RegExp(`\{\{${_v}\}\}`, 'g'), value)
	});
	return resp;
}