AcademySoftwareFoundation / AcademySoftwareFoundation/OpenImageIO

Convert documentation examples into testsuite tests

Open
#3,992 38 comments 0 reactions 0 assignees View on GitHub
devdays devdays25 difficulty/easy docs good first issue help wanted
Dominant language
C++
Stars
2.4k
Forks
698
Avg merge
3d 9h
Merged PRs (30d)
48

Description

The [documentation](https://openimageio.readthedocs.io/) contains lots of code examples embedded in the text. Some of them have bugs or are incorrect in various ways, either because they were never correct (having been typed in for the docs themselves and never directly tested), or were once correct but now the APIs have changed and the example was never updated to match.

To combat this, we would like to go through all the documentation, and to the greatest extent possible, convert every significant code example in the docs into a test -- that is, into actual code that will compile and run every time we run the testsuite -- and then the documentation will merely include the test code by reference, so they can never get out of sync again.

Explanation: https://github.com/OpenImageIO/oiio/wiki/Converting-documentation-examples-to-tests

There are dozens and dozens of code examples in the docs that we could do this with. Small steps -- do this for one or two at a time, that's fine.

Contributor guide

Open the contributing guide

Research direction

Start with the documentation at https://openimageio.readthedocs.io/ and the conversion guidance in the linked wiki page. Choose one or two significant code examples, then identify how to make each compile and run as part of the existing testsuite. The work is done when the documentation includes the tested code by reference and the example is exercised by every test run.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation, testing
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.