DEV Community

Burdette Lamar
Burdette Lamar

Posted on

9 2

Keep Your Example Code Green

Showing example code in your documentation is immensely helpful to your user -- unless the example code is stale or, much worse, broken.

If users runs your example code and it gives errors, how can they have any confidence in the rest of your code.

Question: What to do?

Answer: Run your example code before every commit. (Just like your tests, right?)

Question: How?

Answer: Use a build procedure and file inclusion:

  • Store each example code snippet is in a separate file.
  • In your main document, specify file inclusions for each example code and its output.
  • Have the build procedure (Makefile, Rakefile, Ant, whatever):
    1. Execute each example, capturing its output to a separate file.
    2. Run a file inclusion process that merges each code snippet and its output into the main document (README, whatever).

So far, so good.

But over at GitHub, the markdown processing does not support file inclusion.

Shameless plug: My Ruby gem markdown_helper is a markdown pre-processor that does support file inclusion. In fact, the project's front page itself makes extensive use of the feature.

So if your project is on GitHub, you can use markdown_helper to merge code and output into your markdown pages.

And, by the way:

  • Your project need not be coded in Ruby. The markdown_helper has a command-line interface that your non-Ruby build procedure can use.
  • File inclusions can be nested: your included files can include still more files.

Check out the use cases.

AWS GenAI LIVE image

Real challenges. Real solutions. Real talk.

From technical discussions to philosophical debates, AWS and AWS Partners examine the impact and evolution of gen AI.

Learn more

Top comments (0)

Billboard image

Create up to 10 Postgres Databases on Neon's free plan.

If you're starting a new project, Neon has got your databases covered. No credit cards. No trials. No getting in your way.

Try Neon for Free →