search

chapel-lang / chapel

a Productive Parallel Programming Language
https://chapel-lang.org
Other
1.8k stars 422 forks source link

documentation includes untested code samples #14337

Open mppf opened 5 years ago

mppf commented 5 years ago

Lots of Chapel documentation has code samples that aren't tested. These code samples go out of date over time and since they are untested, there is no automatic (e.g. nightly) hint that they need to be updated. We would like these to be tested regularly so that the documentation can have good quality.

This has always been a problem for both:

Now that the language specification is in RST (as of PR #14165), all three of these categories of documentation are RST. As a result, it might be practical to create a solution to this problem as part of our RST-related documentation scripting.

The migration of the spec to RST added some support for writing tests in rst for start_test. This could be extended and related scripting could be improved to warn for untested code (say). However the syntax would probably need some polish before it is user-facing as a way of testing code in chpldoc blocks. Issue #11090 discusses that element.

bradcray commented 2 years ago

This is related to https://github.com/chapel-lang/chapel/issues/11090