Inline Docs
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.
Install
npm install -g inline-docs
Running from CLI
Run 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.
Running from javascript
See Module entry point for API details.
Getting started
Writing docs
-
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.
Linking
- 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]]
Refining sources
- 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.
License
MIT