Embed markdown documentation in code.
Ideally, documentation and code are written in parallel. Good code is self-explanitory as far as the "what" is concerned. Documentation is a way to record the "why". Linking related parts together helps other developers understand how the system meets business needs and fits together as a whole.
npm install -g inline-docs
Running from CLI
inline-docs > docs.html in your project's root directory. Creates docs like http://joshwnj.github.io/inline-docs.
See Command line interface for more options.
See Module entry point for API details.
all documentation is written in markdown format. You can do this either in a
.mdfile, or embed a markdown document within the comments of a source code file.
markdown documents will only be used if they pass some basic validation rules. See Validating markdown documents for details.
- every level-1 and level-2 heading becomes a link anchor.
- to link to a level-1 heading use the heading text in brackets like
[[Heading text goes here]]. This will be converted to an html hyperlink when the final docs are generated.
- linking to level-2 headings works the same, except with two parts
[[Heading text goes here][And subheading here]]
- You may come across cases where you want to exclude certain files from being parsed by
inline-docs(eg. to avoid junk in your docs).
- To exclude a single file, add the
/* inline-docs:ignore */directive to the top of the file.
- To exclude a set of files, override the patterns defined at Module entry point: Default options.