Generate an API section for a README.md from inline JSDocs
What? Surely there's other ways to do this already? Yes! But I have opinions!
Examples of the generated Markdown from jsdoc4readme:
Some related works, along with my rationale for not choosing them for my own use. Follow the links and you may find something that works for you:
- jsdoc - this is used internally by jsdoc4readme, it's designed for producing HTML or a structured output. It doesn't have a Markdown generator (nor an external API). I don't want HTML.
- jsdoc-to-markdown - works well but overly complex if you have opinions about formatting that deviate too much (plus I experienced some bugs).
- documentationjs -
npm install documentation⇒
added 631 packages from 624 contributors. Nope nope nope. I'm a simple man with simple needs and hate bloated dependency trees. I also don't like the Markdown formatting.
- gendo - relies on documentationjs and also sets up
gh-pagesfor a web version in addition to README editing.
npm install jsdoc4readme
-g to install as a global tool,
-D to save to a package.json's
jsdoc4readme [--readme] <sourcefile>[, <sourcefile>, ...]
--readme argument will look for a README.md (or README.markdown, or a case insensitive variant) and replace the block between an
## API line and the next
## heading. If you don't supply
--readme, the Markdown will be printed to standard out and you can do what you like with it.
Add a script to package.json for use as
npm run docs (after installing with
npm install jsdoc4readme -D):
License and Copyright
Copyright 2019 Rod Vagg
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.