Feathers: API Docs

Created on 28 Apr 2016  路  13Comments  路  Source: feathersjs/feathers

Developing a Feathers application I found myself quite often combing through the official Docs. As most parts (authentication, client, socket, rest,...) are in some way or another interconnected it would be great to have a purely technical one-stop destination with a clear definition of what methods are available and what options can be used (or just a suitable reference to the underlying technologies' documentations).

I personally think something pretty straight forward like the Underscore Docs would be suitable and significantly improve the development workflow.

Question
Source
picture beevelop
👍4

Most helpful comment

This has been done for Auk and is available at https://docs.feathersjs.com/api/readme.html

picture daffl on 17 Jun 2017
❤2

All 13 comments

Good idea. A cheat-sheet, maybe as a guide, would be nice.

daffl picture daffl on 29 Apr 2016
👍1

@beevelop I assume you mean more than just this: http://docs.feathersjs.com/api/readme.html.

Although this is definitely valuable this is actually a pretty big task because there are so many different repos. In this case I would sort of defer to just looking at the code, unless you have some specific examples. I know that auth docs could be improved quite a bit.

ekryski picture ekryski on 22 May 2016

I have done a utility that builds a table of contents for the feathers docs. Here's how it looks:

kulakowka picture kulakowka on 3 Sep 2016

It parses gitbook, and builds a table of contents based on the headings and subheadings for each page.

kulakowka picture kulakowka on 3 Sep 2016

May be we can use something like JSDoc for creating API Docs?

I think it would be convenient if we make the documentation in all official plugins on a single page.

kulakowka picture kulakowka on 6 Sep 2016

I found a theme for jsdoc: minami

underscorejs uses it.

687474703a2f2f7075752e73682f674f794e652f363663336164636239372e706e67

kulakowka picture kulakowka on 6 Sep 2016

We can create API docs in markdown format with documentation.js or dox.
This will allow us to automatically generate documents for API, and then we can use the usual gitbook.

kulakowka picture kulakowka on 6 Sep 2016

I personally like how Slate looks for documentation https://github.com/lord/slate

NetOperatorWibby picture NetOperatorWibby on 16 Sep 2016

Today I tried this: jsdoc-to-markdown

It's amazing! And very simple!

2016-09-17 0 55 25

Add to package.json:

"scripts": {
    "docs": "jsdoc2md \"src/**/*.js\" > docs/api.md",
}

And run buld:

npm run docs
kulakowka picture kulakowka on 16 Sep 2016
👍2

For preview docs i uses markserv. It serves Markdown files as GitHub style HTML and LiveReloads your files in the browser as you edit.

cd path/to/docs
markserv
kulakowka picture kulakowka on 17 Sep 2016
👍1

We are going to restructure the documentation for the next release with every page containing a Summary + API, Example and detailed explanations and a big Ecosystem chapter (for discussion see https://github.com/feathersjs/feathers-docs/issues/251#issuecomment-258071621). This will hopefully make finding the API easier while not requiring two documentation sections.

daffl picture daffl on 8 Nov 2016
🎉2

This has been done for Auk and is available at https://docs.feathersjs.com/api/readme.html

daffl picture daffl on 17 Jun 2017
❤2

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue with a link to this issue for related bugs.

lock[bot] picture lock[bot] on 7 Feb 2019
Was this page helpful?
0 / 5 - 0 ratings

Related issues

rstegg picture rstegg  路  3Comments
intumwa picture intumwa  路  3Comments
huytran0605 picture huytran0605  路  3Comments
RickEyre picture RickEyre  路  4Comments
davigmacode picture davigmacode  路  3Comments