JSDoc Tutorial Include Source File

Question

I have a JavaScript project that's documented using JSDoc3, and I'm working on adding tutorials (written in HTML). I have example code in my project consisting of a series of scripts that the user can run, and I'm essentially writing tutorials to explain what each example script does. I'd like to have a blurb of explanatory text at the top of each tutorial, and then include an example script. I can copy-and-paste example code into a tutorial file and get it formatted correctly, but ideally I'd like to include the file so that I don't have to maintain the example code in two separate locations. How can I accomplish this using JSDoc3?

Answer 1

I don't have a pure, JSDoc-only solution, but I know, that Mocha (testing framework) could generate good enough documentation from test-files, using doc-reporter

Workaround 1

Workaround could look like this:

1. convert your samples to the tests for mocha
2. run mocha --reporter=doc for new test files
3. forward the output from mocha to preprocessor to generate styled documentation

With this solution you will get one bonus: the examples will be tested.

Workaround 1.a

There are other mocha reporters: html, markdown, json. We can use markdown reporter in the following variation of the first solution:

1. samples => tests
2. run mocha -r markdown
3. store the mocha's output to the root of JSDoc tutorials
4. run jsdoc (with tutorials generating)

The main difference: utilizing the tutorial feature of JSDoc