Skip to content

Migrate documentation of special cases to use math directives #519

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kgryte opened this issue Nov 27, 2022 · 2 comments
Open

Migrate documentation of special cases to use math directives #519

kgryte opened this issue Nov 27, 2022 · 2 comments
Labels
Maintenance Bug fix, typo fix, or general maintenance. Narrative Content Narrative documentation content.

Comments

@kgryte
Copy link
Contributor

kgryte commented Nov 27, 2022

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.

@kgryte kgryte added Maintenance Bug fix, typo fix, or general maintenance. Narrative Content Narrative documentation content. labels Nov 27, 2022
@honno
Copy link
Member

honno commented Nov 29, 2022

This would be sweet. For reference the existing parsing work in the test suite could be a good reference to basically do the reverse and generate the majority of the structured pre-complex data, so I'll have to explore this myself and report back.

I assume we wouldn't be able to comfortably do this for a release this year.

@asmeurer
Copy link
Member

Structured data would be great (c.f. #49).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Maintenance Bug fix, typo fix, or general maintenance. Narrative Content Narrative documentation content.
Projects
None yet
Development

No branches or pull requests

3 participants