Code samples in API documentation

Nat Pryce has an interesting idea for maintaining code samples in API documentation. The gist is that the examples are maintained as programs in same source control repository as the API itself. This allows them to be tested and kept sync with the evolving API. Special markup is used in the program to write the prose and explanations. From the source code a HTML-document is generated that shows the prose and the actual program. While a reader navigates the explanations one by one, only the current explanation is shown, which reduces the clutter and guides the reader through the program step by step.

I think this is pretty nifty tool. Especially the ability to test the examples is important in order to keep them in sync with the code. My approach has been using Sphinx + DocTest as shown in pyherc – documentation.

More can be read from here. The tool itself is available here.

One thought on “Code samples in API documentation

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s