Migrate documentation of special cases to use math directives
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 25/100
- Issue type
- Documentation
- Clarity
- Needs clarification
- Activity status
- Stale
- Domain
- documentation, testing
Research direction
Start by locating the API documentation's special-case descriptions and the array API test suite logic that extracts special values and expected results from narrative content. Review how math directives are supported in the documentation format and determine how the suite can consume the migrated cases. Done means the special cases render with math directives without breaking test extraction; structured data is an optional design consideration.
Written by the indexing model from the issue text.
Description
The documentation of special cases in API documentation predates the specification's embrace of reST and GitHub support for mathematical equations in Markdown. As such, special cases use code blocks for numerical values and mathematical symbols. We should migrate to using math directives for better and more succinct rendering.
Adoption of math directives needs to be coordinated with the array API test suite, which, TMK, relies on special cases being described in a particular format within narrative content. Migration to math directives would thus break the test suite's current parsing logic for extracting special values and the associated expected result.
During this migration, we may want to consider providing structured data (e.g., as JSON) describing special cases which can be more readily consumed by downstream consumers, such as the array API test suite, and prevent implicit dependencies on how narrative content is written.
- Dominant language
- Python
- Stars
- 281
- Forks
- 52
- PR merge metrics
- No merged PRs in 30d
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from data-apis/array-api
-
Difficulty 1/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
-
Difficulty 5/5 Over a week Newbie friendliness 35/100
-
Maintenance
-
Difficulty 5/5 Over a week Newbie friendliness 25/100
All issues in data-apis/array-api
Similar issues
-
documentation help wanted
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
simonw/sqlite-utils#872 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100