From a222842dcfaa363806c514571aa9f927043aba48 Mon Sep 17 00:00:00 2001 From: Harminder virk Date: Wed, 22 May 2019 18:31:13 +0530 Subject: [PATCH] docs: add documentation --- README.md | 67 ++++- docs/README.md | 113 +++++++++ docs/classes/_application_.application.md | 295 ++++++++++++++++++++++ docs/modules/_application_.md | 12 + docs/modules/_contracts_.md | 8 + docs/modules/_rcparser_.md | 30 +++ package.json | 8 +- typedoc.js | 1 + 8 files changed, 523 insertions(+), 11 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/classes/_application_.application.md create mode 100644 docs/modules/_application_.md create mode 100644 docs/modules/_contracts_.md create mode 100644 docs/modules/_rcparser_.md create mode 100644 typedoc.js diff --git a/README.md b/README.md index fc14676..4f7e660 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,70 @@ +
+ +
+ +# Adonis application +[![circleci-image]][circleci-url] [![npm-image]][npm-url] ![](https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript) + +The application class for AdonisJs to know more about the environment and project structure of your AdonisJs applications. + ## Table of contents -- [@poppinss/application](#poppinssapplication) - - [Change log](#change-log) - - [Contributing](#contributing) - - [Authors & License](#authors--license) +- [Usage](#usage) +- [rcParser](#rcparser) +- [API Docs](#api-docs) +- [Change log](#change-log) +- [Contributing](#contributing) +- [Authors & License](#authors--license) -# @poppinss/application +## Usage +Ideally you shouldn't be installing this module directly, hence it is part of AdonisJs by default. However, installing module directly is helpful when testing AdonisJs specific addons. + +```sh +npm i @poppinss/application + +# Yarn +yarn add @poppinss/application +``` + +and then use it as follows: + +```ts +import { Application } from '@poppinss/application' +import { Ioc } from '@adonisjs/fold' + +const app = new Application( + '1.0.0', + __dirname, + new Ioc(), + require('./adonisrc.json'), +) +``` + +The constructor takes 4 arguments, which you fake during testings. + +| Argument position | Description | +|------------------|------------------| +| `0 (version)` | The version of `@adonisjs/core` package | +| `1 (appRoot)` | The application root | +| `3 (ioc)` | Instance of IoC container | +| `4 (rcContents)` | Contents of `.adonisrc.json` file. You can also provide an empty object | + +## rcParser +The application instance will parse the contents of `.adonisrc.json` file. However, if you need the parser, you can access and use it as follows. + +```ts +import { rcParser } from '@poppinss/application' +rcParser.parse(require('.adonisrc.json')) +``` + +## API Docs +Following are the autogenerated files via Typedoc -[![circleci-image]][circleci-url] -[![npm-image]][npm-url] -![](https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript) +* [API](docs/README.md) ## Change log diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..f41b335 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,113 @@ + +![](https://res.cloudinary.com/adonisjs/image/upload/q_100/v1557762307/poppinss_iftxlt.jpg) + +Adonis application +================== + +[![circleci-image](https://img.shields.io/circleci/project/github/poppinss/application/master.svg?style=for-the-badge&logo=circleci)](https://circleci.com/gh/poppinss/application "circleci") [![npm-image](https://img.shields.io/npm/v/@poppinss/application.svg?style=for-the-badge&logo=npm)](https://npmjs.org/package/@poppinss/application "npm") ![](https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript) + +The application class for AdonisJs to know more about the environment and project structure of your AdonisJs applications. + +Table of contents +----------------- + +* [@poppinss/application](#poppinssapplication) + * [Change log](#change-log) + * [Contributing](#contributing) + * [Authors & License](#authors--license) + +Usage +----- + +Ideally you shouldn't be installing this module directly, hence it is part of AdonisJs by default. However, installing module directly is helpful when testing AdonisJs specific addons. + +```sh +npm i @poppinss/application + +# Yarn +yarn add @poppinss/application +``` + +and then use it as follows: + +```ts +import { Application } from '@poppinss/application' +import { Ioc } from '@adonisjs/fold' + +const app = new Application( + '1.0.0', + __dirname, + new Ioc(), + require('./adonisrc.json'), +) +``` + +The constructor takes 4 arguments, which you fake during testings. + +Argument position + +Description + +`0 (version)` + +The version of `@adonisjs/core` package + +`1 (appRoot)` + +The application root + +`3 (ioc)` + +Instance of IoC container + +`4 (rcContents)` + +Contents of `.adonisrc.json` file. You can also provide an empty object + +rcParser +-------- + +The application instance will parse the contents of `.adonisrc.json` file. However, if you need the parser, you can access and use it as follows. + +```ts +import { rcParser } from '@poppinss/application' +rcParser.parse(require('.adonisrc.json')) +``` + +API Docs +-------- + +Following are the autogenerated files via Typedoc + +* [API](docs/README.md) + +Change log +---------- + +The change log can be found in the [CHANGELOG.md](CHANGELOG.md) file. + +Contributing +------------ + +Everyone is welcome to contribute. Please go through the following guides, before getting started. + +1. [Contributing](https://adonisjs.com/contributing) +2. [Code of conduct](https://adonisjs.com/code-of-conduct) + +Authors & License +----------------- + +\[Harminder virk\]([https://github.com/Harminder](https://github.com/Harminder) virk) and [contributors](https://github.com/poppinss/application/graphs/contributors). + +MIT License, see the included [MIT](LICENSE.md) file. + +## Index + +### External modules + +* ["Application"](modules/_application_.md) +* ["contracts"](modules/_contracts_.md) +* ["rcParser"](modules/_rcparser_.md) + +--- + diff --git a/docs/classes/_application_.application.md b/docs/classes/_application_.application.md new file mode 100644 index 0000000..bdb2878 --- /dev/null +++ b/docs/classes/_application_.application.md @@ -0,0 +1,295 @@ +[@poppinss/application](../README.md) > ["Application"](../modules/_application_.md) > [Application](../classes/_application_.application.md) + +# Class: Application + +The main application instance to know about the environment, filesystem in which your AdonisJs app is running + +## Hierarchy + +**Application** + +## Implements + +* `ApplicationContract` + +## Index + +### Constructors + +* [constructor](_application_.application.md#constructor) + +### Properties + +* [appName](_application_.application.md#appname) +* [appRoot](_application_.application.md#approot) +* [autoloadsMap](_application_.application.md#autoloadsmap) +* [container](_application_.application.md#container) +* [directoriesMap](_application_.application.md#directoriesmap) +* [environment](_application_.application.md#environment) +* [exceptionHandlerNamespace](_application_.application.md#exceptionhandlernamespace) +* [inDev](_application_.application.md#indev) +* [inProduction](_application_.application.md#inproduction) +* [preloads](_application_.application.md#preloads) +* [ready](_application_.application.md#ready) +* [version](_application_.application.md#version) + +### Methods + +* [configPath](_application_.application.md#configpath) +* [databasePath](_application_.application.md#databasepath) +* [makePath](_application_.application.md#makepath) +* [migrationsPath](_application_.application.md#migrationspath) +* [publicPath](_application_.application.md#publicpath) +* [resourcesPath](_application_.application.md#resourcespath) +* [seedsPath](_application_.application.md#seedspath) +* [viewsPath](_application_.application.md#viewspath) + +--- + +## Constructors + + + +### constructor + +⊕ **new Application**(version: *`string`*, appRoot: *`string`*, container: *`IocContract`*, rcContents: *`any`*): [Application](_application_.application.md) + +**Parameters:** + +| Name | Type | +| ------ | ------ | +| version | `string` | +| appRoot | `string` | +| container | `IocContract` | +| rcContents | `any` | + +**Returns:** [Application](_application_.application.md) + +___ + +## Properties + + + +### appName + +**● appName**: *`string`* + +___ + + +### appRoot + +**● appRoot**: *`string`* + +___ + + +### autoloadsMap + +**● autoloadsMap**: *`Map`<`string`, `string`>* = new Map() + +___ + + +### container + +**● container**: *`IocContract`* + +___ + + +### directoriesMap + +**● directoriesMap**: *`Map`<`string`, `string`>* = new Map() + +___ + + +### environment + +**● environment**: *"web" \| "console" \| "test" \| "unknown"* = "unknown" + +___ + + +### exceptionHandlerNamespace + +**● exceptionHandlerNamespace**: *`string`* + +___ + + +### inDev + +**● inDev**: *`boolean`* = !this.inProduction + +___ + + +### inProduction + +**● inProduction**: *`boolean`* = process.env.NODE_ENV === 'production' + +___ + + +### preloads + +**● preloads**: *`PreloadNode`[]* = [] + +___ + + +### ready + +**● ready**: *`boolean`* = false + +___ + + +### version + +**● version**: *`string`* + +___ + +## Methods + + + +### configPath + +▸ **configPath**(...paths: *`string`[]*): `string` + +Make path to a file or directory relative from the config directory + +**Parameters:** + +| Name | Type | +| ------ | ------ | +| `Rest` paths | `string`[] | + +**Returns:** `string` + +___ + + +### databasePath + +▸ **databasePath**(...paths: *`string`[]*): `string` + +Make path to a file or directory relative from the database path + +**Parameters:** + +| Name | Type | +| ------ | ------ | +| `Rest` paths | `string`[] | + +**Returns:** `string` + +___ + + +### makePath + +▸ **makePath**(...paths: *`string`[]*): `string` + +Make path to a file or directory relative from the application path + +**Parameters:** + +| Name | Type | +| ------ | ------ | +| `Rest` paths | `string`[] | + +**Returns:** `string` + +___ + + +### migrationsPath + +▸ **migrationsPath**(...paths: *`string`[]*): `string` + +Make path to a file or directory relative from the migrations path + +**Parameters:** + +| Name | Type | +| ------ | ------ | +| `Rest` paths | `string`[] | + +**Returns:** `string` + +___ + + +### publicPath + +▸ **publicPath**(...paths: *`string`[]*): `string` + +Make path to a file or directory relative from the public path + +**Parameters:** + +| Name | Type | +| ------ | ------ | +| `Rest` paths | `string`[] | + +**Returns:** `string` + +___ + + +### resourcesPath + +▸ **resourcesPath**(...paths: *`string`[]*): `string` + +Make path to a file or directory relative from the resources path + +**Parameters:** + +| Name | Type | +| ------ | ------ | +| `Rest` paths | `string`[] | + +**Returns:** `string` + +___ + + +### seedsPath + +▸ **seedsPath**(...paths: *`string`[]*): `string` + +Make path to a file or directory relative from the seeds path + +**Parameters:** + +| Name | Type | +| ------ | ------ | +| `Rest` paths | `string`[] | + +**Returns:** `string` + +___ + + +### viewsPath + +▸ **viewsPath**(...paths: *`string`[]*): `string` + +Make path to a file or directory relative from the views path + +**Parameters:** + +| Name | Type | +| ------ | ------ | +| `Rest` paths | `string`[] | + +**Returns:** `string` + +___ + diff --git a/docs/modules/_application_.md b/docs/modules/_application_.md new file mode 100644 index 0000000..9aa063d --- /dev/null +++ b/docs/modules/_application_.md @@ -0,0 +1,12 @@ +[@poppinss/application](../README.md) > ["Application"](../modules/_application_.md) + +# External module: "Application" + +## Index + +### Classes + +* [Application](../classes/_application_.application.md) + +--- + diff --git a/docs/modules/_contracts_.md b/docs/modules/_contracts_.md new file mode 100644 index 0000000..d1c7f2e --- /dev/null +++ b/docs/modules/_contracts_.md @@ -0,0 +1,8 @@ +[@poppinss/application](../README.md) > ["contracts"](../modules/_contracts_.md) + +# External module: "contracts" + +## Index + +--- + diff --git a/docs/modules/_rcparser_.md b/docs/modules/_rcparser_.md new file mode 100644 index 0000000..9131c4c --- /dev/null +++ b/docs/modules/_rcparser_.md @@ -0,0 +1,30 @@ +[@poppinss/application](../README.md) > ["rcParser"](../modules/_rcparser_.md) + +# External module: "rcParser" + +## Index + +### Functions + +* [parse](_rcparser_.md#parse) + +--- + +## Functions + + + +### parse + +▸ **parse**(contents: *`any`*): `RcFile` + +**Parameters:** + +| Name | Type | +| ------ | ------ | +| contents | `any` | + +**Returns:** `RcFile` + +___ + diff --git a/package.json b/package.json index 8969456..3d4a975 100644 --- a/package.json +++ b/package.json @@ -10,7 +10,7 @@ "lint": "tslint --project tsconfig.json", "clean": "del build", "compile": "npm run lint && npm run clean && tsc", - "build": "npm run compile", + "build": "npm run compile && typedoc --theme markdown --excludePrivate --mdHideSources && git add docs", "commit": "git-cz" }, "keywords": [ @@ -34,6 +34,9 @@ "ts-node": "^8.1.0", "tslint": "^5.16.0", "tslint-eslint-rules": "^5.4.0", + "typedoc": "^0.14.2", + "typedoc-plugin-external-module-name": "^2.1.0", + "typedoc-plugin-markdown": "^1.2.1", "typescript": "^3.4.5" }, "nyc": { @@ -62,7 +65,6 @@ } }, "dependencies": { - "@poppinss/utils": "^1.0.1", - "ts-essentials": "^2.0.7" + "@poppinss/utils": "^1.0.1" } } diff --git a/typedoc.js b/typedoc.js new file mode 100644 index 0000000..879b8d7 --- /dev/null +++ b/typedoc.js @@ -0,0 +1 @@ +module.exports = require('@adonisjs/mrm-preset/_typedoc.js')()