Manpages And Node Modules
I’ve been thinking a lot lately about documentation. The node community is somewhat known for having poor documentation and issues with discoverablity. While the python community has fantastic tools like Read the Docs, we are many times left with a single readme.
Keeping everything small
Our “One readme per package” practice fits in well with the small
module philosophy. But It can be painful digging around in
node-modules directories looking for that readme. Users generally
will just open up the repo and view the nicely formatted markdown in
the github ui. But what about offline development? This was a pain
point for us mentors at the most recent NodeSchool.io. Specifically
digging around for Async docs when students were continually being
booted off of the WiFi.
man {package-name}
Being that our community loves to follow the unix philosophy why not take advantage of tools developers are already familiar with? Lets generate man pages for all of our node modules.
man page generation
Generating man pages out of existing readme’s is extremely straight forward. There’s already a module for that.
Go ahead and install marked-man
npm install -g marked-man
Now we just need to point marked-man to the markdown file we want to generate our manpage from.
marked-man README.md > doc/package-name.1
Try it out by running
man path/to/manpage
You should get something like this.
Now all we need to do is let npm know about our manpage. We’ll edit our package.JSON.
If the module is installed globally with npm it will copy the manpages
from the path specified in the man property to
{prefix}/share/man.
It’s as simple as that. If you’d like to dig in a little bit deeper on this subject take a look at these resources.
If your never without an internet connection or just hate man pages you can always run the
npm docs … command:
npm docs {package-name}
Go forth and generate more accessible documentation!
UPDATE
The npm feature written about in this blog post is currently not working. You can track the issue here.
blog comments powered by Disqus