search

marksmccann / node-sass-extra

A drop-in replacement for node-sass' Node API that adds support for globs, promises and more.
MIT License
2 stars 1 forks source link

Cleanup auto-magic docs #45

Closed marksmccann closed 5 years ago

marksmccann commented 5 years ago

There are a few artifacts from the auto-magic docs from jsdoc-to-markdown that we should clean up and/or organize. We can customize the output of the docs via the README.hbs template.

https://github.com/jsdoc2md/jsdoc-to-markdown/wiki/Cherry-picking-which-documentation-appears-in-output

marksmccann commented 5 years ago

@phillipluther I attempted this issue, and while I as able to get it to work, I am not sure it was worth the effort. The template file was a getting a little too complicated for it to be worth it. I am tempted to remove jsdoc2markdown and write the docs manually. While it might mean some duplication between the comments in the script and the content in the readme, I think it will ultimately be easier and give us more control. It would also clean up the index file a lot. Do you have any heartache with that? As cool as the auto-magic docs were, I think I have learned they may not be worth it, at least not for a small package like ours. Perhaps they make more sense for a larger library. If you agree, I think I will pick up that task tonight.

phillipluther commented 5 years ago

Sounds good to me; editing the markdown files doesn't seem like a major obstacle. Oddly, even though there might be some duplication, it somehow feels easier/less abstract.