Tips to keep documentation code examples up to date

Separate code from text and automate testing to reduce maintenance

Documentation code examples break. The SDK changes. Nobody updates the examples. Users copy broken code and get frustrated.

Here’s how to make code examples easier to maintain and test.

Note: I’m using Sphinx here, but the principles apply to any documentation system.

The problem with inline code

Here’s a typical documentation page mixing code and text:

Example
=======

To order a pizza using the Python SDK, call the
``order`` method by passing the
pizzas you want, your customer ID, and the delivery
service as the parameters.

The following examples show you how to order a 
Hawaiian pizza to take away.

.. code-block:: python

    api = pizza.Api()

    api.order(
      pizzas=[
      {’code’:pizza.pizza_codes.HAWAIIAN, 
        ‘quantity’:1}
        ], 
        customer_id=’dgarcia360’, 
        serviceType=pizza.service_types.TAKE_AWAY)

When the SDK updates, you have to:

1. Find every affected example.

2. Copy/paste each one into a file.

3. Test it manually.

4. Update the docs.

You can’t verify the code you tested is the same code displayed in the docs.

Step 1: Separate code from text

Move code examples to separate files:

documentation-project/
├── index.rst
├── order.rst
├── examples/
│   ├── javascript
│   └── python
│       ├── order.py
│       ├── tests/
│       └── requirements.txt

Now you can:

• Run the code and add tests

• Use linters to check formatting

• Execute examples without copy/paste

Step 2: Import code into docs

Use a directive like Sphinx’s literalinclude directive to render code files:

.. literalinclude:: examples/python/order.py
    :language: python

Step 3: Highlight code subsets

Sometimes you only need part of a file. Use comment tags to mark sections:

# block 01
api = pizza.Api()
# endblock 01

# block 02
api.order(
    pizzas=[
        {’code’:pizza.pizza_codes.HAWAIIAN, 
        ‘quantity’:1}
    ], 
    customer_id=’dgarcia360’, 
    serviceType=pizza.service_types.TAKE_AWAY)
# endblock 02

... and then, detect those tags with the help of the directive.

.. literalinclude:: /pizza/order.py
    :language: python
    :start-after: # block 02
    :end-before: # endblock 02

You can also use line numbers:

.. literalinclude:: /pizza/order.py
    :language: python
    :lines: 10-15

But line numbers break easily. Add one import statement at the top of the file and every line number shifts. Your docs now show the wrong code. Comment tags stay anchored to the code they mark, even when the file changes.

The new update process

When the SDK releases a new version:

1. Update dependencies in the examples folder.

2. Run the code and see what fails.

3. Fix the broken examples.

4. Push changes. Docs update automatically.

The real benefit

This doesn’t eliminate code example maintenance. It just makes it testable.

When your tests pass, your code examples work. When they fail, you know which examples broke and can fix them before users find out.

Separate code from docs, test it, and import it. That’s it.