Best tool for generating docs? (from source + markdown docs)


#1

Hi guys,

I’d like to start documenting my project and (like always) there are 2 sources of documentation:

  1. Source-Code API documentation
  2. Markdown Project Documentation

Coming from python I have used http://sphinx-doc.org/ before, which is pretty cool as it generates a SEARCHABLE html, for example like this: http://nodewatcher.readthedocs.org/en/development/.

Having an easy search-interface for both 1) & 2) is a really great feature
and helps the team to share knowledge.

How do you guys do this?
Is there a open-source example to have a look at?


#2

Bumper… does anyone have a suggestion?


#3

I use https://github.com/fabienb4/meteor-jsdoc. It generates a meteor-style documentation application from JSDoc documentation in your code. It supports inline markdown, and in my own fork you can also include .md files.

There is no search feature yet (except ctrl-f), but since everything is in one page, ctrl+f works pretty well.

IMO it is the best documentation tool available.


#4

omg, @jorgeer! This is awesome!

I just got it up and running, and this is the best thing since sliced bread! Perfect, perfect, perfect! THANK YOU!


#5

Did anybody manage to run meteor-jsdoc on MacOS? I tried it some days ago, but I only got an empty documentation. And the maintainer says that he does not have a Mac to check if its running on this system.


#6

Unfortunately (well, not really for me), I don’t have an IOS machine readily available to check with my own project, but I’m guessing that since you get an empty (working?) app out of it, it is the JSDoc that complains, but isn’t reporting what the problem is.

A few things to make sure though, you are using the @summary tag in your documentation? You ran meteor-jsdoc build?

Otherwise, I would clone the project and add a console.log in the actions file, and seeing what stdout and stderr is saying.
Not very user friendly unfortunately.


#7

No, I’m not using @summary, and yes, I ran meteor-jsdoc build.

Even the sample included in the meteor-jsdoc repository isn’t working. The docs are empty, just like for my custom project.

What do you mean by “actions” file?


#8

As per the Docs, though a bit hidden

The @summary tag is required for the docs to be generated properly. Any method docs without it won't be processed by meteor-jsdoc.

Sometimes, error messages end up Here, in the logs.stdout callback variable, but I would definitely add a few @summary tags first and build again first. Check your doc project’s /client/data/ directory to see if the docs have been retrieved from your code, and be sure that your configuration file is set up correctly.


#9

Sweet! I want to use that


#10

Thanks, will try to add the @summary tags! Still wondering why the sample app is not working, though.


#11

Yeah, we’re running on MacOS, and it’s working like a charm. Port 3333.

Also, apparently it only parses jsdoc tags from the /packages directory? And does it not support gitmodules?


#12

Hmm, for me it parses both my local project, and symlinked local packages in /packages, I see no restriction for the the /packages dir only, as per the build script. I don’t see why modules should be ignored as long as they can be found from the top level directory.


#13

Thank you much for letting us know that this can/should work for local project and symlinked packages. We obviously have a bit more tinkering to do! :slight_smile: