Js-ipfs: Awesome API Documentation Endeavour

Created on 22 Nov 2016 · 35Comments · Source: ipfs/js-ipfs

We want to improve the documentation in the whole project and for that this endeavour exists.
To improve the documentation we settled on using jsdoc style inline comments to describe the APIs and after that using documentation.js to generate beautiful docs.

If you want to help out, please comment on this issue which module you are tackling.

Test Instructions

~~Currently the integration into aegir is not yet done, so when documenting you can use documentation.js directly to test that everything works fine.~~

Update aegir to ^9.2.0
Add a script to package.json with "docs": "aegir-docs"
Run npm run docs
open docs/index.html in your favorite browser

Modules

IPFS

| Name | JSDOC | Assignee |
|-------|--------|-----------|
| js-ipfs-bitswap
| js-libp2p-ipfs-browser
| js-libp2p-ipfs
| js-ipfs-block
| js-ipfs-api | https://github.com/ipfs/js-ipfs-api/pull/469 | |
| js-ipfs | https://github.com/ipfs/js-ipfs/pull/651 | @dignifiedquire
| js-ipfs-unixfs-engine
| js-ipfs-block-service
| js-fs-pull-blob-store
| js-idb-pull-blob-store
| js-ipfs-repo
| interface-pull-blob-store

IPLD

| Name | JSDOC | Assignee |
|-------|--------|-----------|
| js-cid | https://github.com/ipfs/js-cid/pull/9 | @dignifiedquire |
| js-ipld-dag-cbor
| js-ipld-resolver
| js-ipld-dag-pb
| js-ipld-eth-block

libp2p

| Name | JSDOC | Assignee |
|-------|--------|-----------|
| js-libp2p-spdy
| js-libp2p-webrtc-star
| js-libp2p-floodsub
| js-peer-info | https://github.com/libp2p/js-peer-info/pull/31 | @dignifiedquire |
| js-peer-id | https://github.com/libp2p/js-peer-id/pull/41 | @dignifiedquire |
| js-libp2p-crypto | https://github.com/libp2p/js-libp2p-crypto/pull/48 | @dignifiedquire |
| js-peer-book | https://github.com/libp2p/js-peer-book/pull/14 | @dignifiedquire |
| js-libp2p-secio
| js-libp2p-websockets
| js-libp2p-identify | https://github.com/libp2p/js-libp2p-identify/pull/22 | @dignifiedquire |
| js-libp2p-tcp | https://github.com/libp2p/js-libp2p-tcp/pull/50 | @dignifiedquire |

multiformats

| Name | JSDOC | Assignee | URL | Shipped |
|-------|--------|-----------|------|-------|
| js-multiaddr | https://github.com/multiformats/js-multiaddr/pull/31 | @VictorBjelkholm | https://multiformats.github.io/js-multiaddr/ | ✅ |
| js-multibase | https://github.com/multiformats/js-multibase/pull/9 | @dignifiedquire | https://multiformats.github.io/js-multibase/ | ✅ |
| js-multistream-select | https://github.com/multiformats/js-multistream-select/pull/28 | @dignifiedquire | https://multiformats.github.io/js-multistream-select/ | ✅ |
| js-multihashing-async | https://github.com/multiformats/js-multihashing-async/pull/5 | @dignifiedquire | https://multiformats.github.io/js-multihashing-async/ | ✅ |
| js-multicodec | https://github.com/multiformats/js-multicodec/pull/9 | @dignifiedquire | https://multiformats.github.io/js-multicodec/ | ✅ |
| js-multihash | https://github.com/multiformats/js-multihash/pull/23 | @dignifiedquire | https://multiformats.github.io/js-multihash/ | ✅ |

Other work

[x] Aegir integration of documentation.js https://github.com/dignifiedquire/aegir/issues/77
[x] Clean documentation theme: https://github.com/dignifiedquire/clean-documentation-theme

awesome endeavour help wanted

Source

dignifiedquire

❤3 👍3

Most helpful comment

Shipped the multiformats docs :)

dignifiedquire on 14 Dec 2016

❤2 🎉2 😄2 👍2

All 35 comments

Thanks @dignifiedquire! I would love to help out with either js-ipfs-api or js-ipfs! :hugs: Also, I can probably tackle js-multiaddr

victorb on 22 Nov 2016

❤1

Published a first version of the new theme on npm: http://npmjs.com/clean-documentation-theme
Published test version of documentation for peer-id here: http://libp2p.github.io/js-peer-id

dignifiedquire on 2 Dec 2016

👍1

@dignifiedquire we should probably add a link to the repository in the top right or something like that in the theme as well

victorb on 5 Dec 2016

@dignifiedquire we should probably add a link to the repository in the top right or something like that in the theme as well

Yes, but need to implement that first in documentation.js, ref https://github.com/documentationjs/documentation/issues/612

dignifiedquire on 5 Dec 2016

@VictorBjelkholm I take that back, added it :)

dignifiedquire on 5 Dec 2016

@VictorBjelkholm @diasdavid just created https://github.com/dignifiedquire/aegir/pull/78

dignifiedquire on 5 Dec 2016

Additional todos for (not needed for initial release though)

[ ] Add @enum support to documentation.js
[ ] Improve @memberof and @namespace handling for documentation.js
[ ] Figure out a way to display and handle nested definitions in documentation.js + clean-documentation-theme

dignifiedquire on 7 Dec 2016

@dignifiedquire this is shaping to be awesome! ❤️

I believe to make this a perfect landing, we just need to make sure that a) feedback is requested, b) feedback is collected.

Let's focus on getting js-ipfs and js-ipfs-api done first as those will be the most used doc pages.

daviddias on 7 Dec 2016

Working on libp2p-tcp I realised that the event support in clean-documentation-them and documentation.js is not as good as we need it to be, will work on this to get it fixed as we do need this.

Relevant issues:

dignifiedquire on 8 Dec 2016

We talked about an introduction section at the beginning, that give installation instructions and an overview of the module at the beginning. Similar to the usage section we have in the readmes currently. The main issue I'm having here right now is that we need to a) write these and b) find a way to properly synchronise them between all the repos.

dignifiedquire on 12 Dec 2016

@dignifiedquire if we want to do something similar to how you did in js-peer-info and in js-multiaddr (https://github.com/multiformats/js-multiaddr/pull/31/files#diff-34c4da6d4768d05e50db99357a299b5c) and share between all modules, then we could probably put most things in a template for reuse that gets evaluated on docs-build. The only thing that is unique really is the module name, short description and the initial example.

victorb on 12 Dec 2016

@VictorBjelkholm yeah this is what I got so far https://gist.github.com/dignifiedquire/e4a8147845a6e359a49374cf6238121f

dignifiedquire on 12 Dec 2016

@dignifiedquire looks good. I think we can get away with just having name though, instead of the different versions. npm-name would just be name with 'js-' in front. safe-name would be name but with first letter being uppercase (or just name), removing any dashes.

Then if we put the example in a different file, we can also easily integrate with RunKit (TonicDev) with "tonicExampleFilename": "example.js"

Looks good :+1:

victorb on 12 Dec 2016

@VictorBjelkholm take a look: https://github.com/dignifiedquire/aegir/pull/80

dignifiedquire on 12 Dec 2016

👍1

Shipped the multiformats docs :)

dignifiedquire on 14 Dec 2016

❤2 🎉2 😄2 👍2

Awesome work! :D 👏👏👏👏

It is missing the search bar, did that get dropped?

daviddias on 15 Dec 2016

From IRC

19:47 <daviddias> Just learned that with the addition of automatically generated docs, you are deleting any kind of API reference from teh readme
19:48 <daviddias> https://github.com/multiformats/js-multihash/pull/23/files
19:48 <daviddias> and now the section is empty
19:48 <daviddias> there is a lot of value on having API documentation in the readme, it is what get published to npm
19:48 <daviddias> plus, having an empty section https://github.com/multiformats/js-multihash#api is simply not helpful

I see that others like multibase didn't loose their API docs though. Are we generating that section automatically for those? How does this play with Standard-readme? @RichardLitt ?

daviddias on 16 Dec 2016

Sorry, I forgot to add the link to deployed sites back in. Standard readme works with an api section that is simply a link fine.

For updating the usage section I'm investigating some tooling so we can sync these easily across the repos as it is currently outdated in the readme but a pain to update manually everyywhere.

dignifiedquire on 16 Dec 2016

Standard readme works with an api section that is simply a link fine.

Yep. If the documentation is better elsewhere, that's OK.

RichardLitt on 16 Dec 2016

The new docs pages are awesome, but we are at the moment making it worse for discoverability, I keep seeing PR's being merged (i.e: https://github.com/multiformats/js-multihashing-async/pull/5 https://github.com/multiformats/js-multicodec/pull/9) that do not address the fact that the documentation is becoming invisible for users visiting the repo or accessing the module through npm, this is a big issue.

Ideally, we would have a markdown version generated and injected in the README.md (I would prefer to have this), but at least a pointer to the actual documentation needs to be added.

Another item that wasn't addressed so far is search. Everyone agreed that feature was one of the key benefits of having these docs pages, in the same way that http://caolan.github.io/async/ does it. Do we have a plan? I understand that is better to have docs and then add search, but we need to make sure it doesn't get dropped.

Another issue is that we are not respecting the declared ownership/responsibility/maintainer, for example, I'm the Captain of https://github.com/multiformats/js-multihashing-async#maintainers and https://github.com/multiformats/js-multicodec#maintainers and yet my CR wasn't requested in https://github.com/multiformats/js-multihashing-async/pull/5 nor https://github.com/multiformats/js-multicodec/pull/9. I believe this is a lapse that we can quickly improve without enforcing a github policy and lock the branches, if you feel otherwise, we can enable it and get reminded by the tool, I'm fine with it, but would like to hear your opinion first.

UPDATE: Moar cases:

https://github.com/multiformats/js-multistream-select/pull/28

daviddias on 19 Dec 2016

Before I start putting urls into Readmes I would like to suggest to set up simple redirects through our domains so we can easily move away from gh pages. Ie https://docs.multiformats.io/js/multibase

@diasdavid I am sorry about the review, the PR was open for some time and I assumed you would have responded if there was sth specific. I will make sure to ping you next time.

dignifiedquire on 19 Dec 2016

Re search, we currently have single pages and crtl-f works perfectly. Not sure how a simple js search would improve this. For really good search we would have to index the content making the whole setup depend on another server/service.

dignifiedquire on 19 Dec 2016

simple redirects through our domains so we can easily move away from gh pages. Ie https://docs.multiformats.io/js/multibase

Good idea! @lgierth can you help set this up?

@diasdavid I am sorry about the review, the PR was open for some time and I assumed you would have responded if there was sth specific. I will make sure to ping you next time.

All good, thank you :) Let's make sure that READMEs have links to the docs soon though.

daviddias on 19 Dec 2016

Hey all, I'm new to the project and still fumbling my way around, if anyone wants to suggest / challenge me to take a look at something small and self contained and produce docs as a learning exercise, I'd be happy to oblige.

mistakenot on 10 Jan 2017

Sounds great @mistakenot. https://github.com/ipfs/js-ipfs-block should be pretty self contained and a good starting point for writing some documentation. You can look at the referenced pull requests above for examples on how to document things.

dignifiedquire on 11 Jan 2017

From IRC:

14:13 <@daviddias> dignifiedquire: I'm afraid that https://github.com/ipfs/js-ipfs/issues/615 might go into a 'stale endeavour state' and that we miss the opportunity to apply the remedies we talked was week to make sure the state and understanding of the project is lost
14:14 <@daviddias> Could you compile a list of tasks that are left, issues (blockers) and the thinking that someone needs to do in order to make it spectacular?

@flyingzumwalt this would be a good pilot for the freshness remedies :)

daviddias on 12 Jan 2017

Other things that have been considered for this endeavour (so that they are not forgotten)

search within each documentation page
search through docs (docs.ipfs.io
compile both a markdown version and a html version of the docs (markdown should be available in the README

daviddias on 19 Jan 2017

compile both a markdown version and a html version of the docs (markdown should be available in the README

I would very much like this. I'm not too happy with the API section just being a link to somewhere off-site; that means that the documentation is not close to the code. @dignifiedquire Can I help with this? Is there a ticket tracking this, elsewhere?

RichardLitt on 19 Jan 2017

that means that the documentation is not close to the code

the documentation is right in the code, so it's even closer now :P

dignifiedquire on 20 Jan 2017

@dignifiedquire I believe that is not a valid answer. Can you provide @RichardLitt with:

How to use jsdoc to generate markdown docs
Any thoughts you might have to make that a simple thing?

daviddias on 20 Jan 2017

I'm sorry I just don't agree with the notion of stuffing the readme full of api documentation if we don't have to. Especially for projects where the documentation is more than just a couple of methods. Putting it in a separate markdown file which is not tracked in git and published to npm I think makes sense though.

Documentation on how to generate markdown docs using documentations.js can be found here: https://github.com/documentationjs/documentation/tree/master/docs
The gulp task we use is this: https://github.com/documentationjs/gulp-documentation
The changes would need to be made to aegir
- https://github.com/dignifiedquire/aegir/blob/master/tasks/docs/build.js
- Some configuration needs to be added to allow enabling the markdown docs generation.

dignifiedquire on 20 Jan 2017

❤2 👍2

I'm sorry I just don't agree with the notion of stuffing the readme full of api documentation if we don't have to.

Fair.

Putting it in a separate markdown file which is not tracked in git and published to npm I think makes sense though.

Why no git track?

RichardLitt on 27 Jan 2017

Why no git track?

Because it's auto generated and the risk of things getting out of sync on a per commit basis is very high.

dignifiedquire on 29 Jan 2017

For awesome documentation, each example link should be pinned somewhere so that the reader can try the example. E.g. the example for "This is some data" on the examples page doesn't resolve:

https://ipfs.io/ipfs/QmNZiPk974vDsPmQii3YbrMKfi12KTSNM7XMiYyiea4VYZ/example#/ipfs/QmRFTtbyEp3UaT67ByYW299Suw7HKKnWK6NJMdNFzDjYdX/data/readme.md

Also, the links for the example web site on this page don't work:

https://ipfs.io/ipfs/QmNZiPk974vDsPmQii3YbrMKfi12KTSNM7XMiYyiea4VYZ/example#/ipfs/QmRFTtbyEp3UaT67ByYW299Suw7HKKnWK6NJMdNFzDjYdX/websites/README.md