New rs.js module docs

raucao · May 9, 2017, 3:04pm

With the new seperate modules, we can’t use the combined current docs like that anymore. As we were also thinking about switching to a more suitable docs framework, and @silverbucket was using JSDoc in Sockethub already, I stole an idea from him that he used for the Sockethub platforms: build the entire README.md from the JSDoc code comments:

The main benefit, apart from versioned docs, is that this gets synced and displayed on npm.org as well.

Now, this is a module util, so the actual class/prototype and function docs make sense. However, I’m not sure it’s as suitable for general rs.js module docs (but it might be).

For that repo, I added a hook for npm version, so that new docs are automatically built and committed with every version published:

github.com

remotestorage/remotestorage-util-credentials-store/blob/master/package.json#L8


{
  "name": "remotestorage-util-credentials-store",
  "version": "1.2.0",
  "description": "Facilitates encryption and storage of credentials",
  "main": "index.js",
  "scripts": {
    "doc": "jsdoc2md index.js > README.md",
    "preversion": "npm run doc && git add README.md"
  },
  "keywords": [
    "remotestorage",
    "remotestorage-util"
  ],
  "author": "Michiel de Jong <michiel@unhosted.org>",
  "license": "MIT",
  "devDependencies": {
    "jsdoc-to-markdown": "^3.0.0"
  },

Let me know what you think.

raucao · May 9, 2017, 3:35pm

I just added a README for chat-messages, and I think if we publish from JSDoc, we should probably make it so that a generic README intro file gets concatenated with the output from JSDoc:

raucao · November 3, 2017, 4:18pm

I found out that jsdoc-to-markdown allows using templates, so that’s what I did in the shares module now. Works like a charm: