Docs contributions: using typedoc to generate API docs

[paxperscientiam]

Hey @nchanged,

I noticed that the npm "document" script (npm run document) needed updating. Took a while to navigate the changes to typedoc, but I got something working. The command to build the API docs is still npm run document, which outputs to 'docs/api'. Just spin up a server for that directory to explore/test.

The most relevant page is this:
http://localhost:5000/interfaces/config_iconfig.ipublicconfig

Perhaps interfaces are the most important thing? Do you want just the IPublicConfig to be part of the API docs, or should other stuff be included too? I'm wondering if it might be possible to split it into two parts: docs for users and docs for developers/contributors.

EDIT: fixed some bad grammar

[nchanged]

@paxperscientiam thanks, but we don't really use it.. do you still think it's valuable?

[paxperscientiam]

@nchanged, the impetus for leveraging typedoc comes from a desire to keep documentation synchronized with changes to fuse-box API. With that said, my vision is that the typedoc output should be made integral -- if not central -- to fuse-box documentation.

Some thoughts on process:

• There is no mechanism in place to prevent out-of-sync code examples (those that conflict with current API iteration) from being retained after an incompatible change is made to the API. This could be allayed by type-checking example code during build process.
• Build process could write-in code comments that indicate fuse-box version into code examples
• Existing documentation snippets on what specific parts of the API do could be included as comments into the code base, which typedoc would then use for creating explanations that are always synchronized (because you'll naturally have to update the comment when you change the API).

This scratches the surface enough, I think. Better docs would make fuse-box easier to use; if fuse-box is easier to use, adoption and material support would hopefully increase.

EDIT: grammar

[nchanged]

@paxperscientiam could you fix the conflicts?