Convert the specification files to rst format

[steff456]

The main goal is to make the specification files more machine readable and enable sphinx extensions like latex to convert into a pdf. This issue will track the changes by markdown file,

API Specification

• array_object.md - PR PR: Convert array_object.md to rst #345
• broadcasting.md - PR PR: Transform broadcasting.md to .rst #346
• constants.md - PR PR: Transform constants.md to rst format #347
• creation_functions.md - PR Transform creation_functions.md to rst #348
• data_type_functions.md - PR PR: Transform data_type_functions.md to rst #349
• data_types.md - PR PR: Transform data_types.md to rst #350
• elementwise_functions.md - PR PR: Transform elementwise_functions.md to rst #351
• function_and_method_signatures.md - PR PR: Transform function and method signatures to rst #352
• indexing.md - PR PR: Transform indexing.md to rst #353
• manipulation_functions.md - PR PR: Transform manipulation_functions.md to rst #354
• linear_algebra_functions.md - PR PR: Transform linear algebra functions md to rst #367
• searching_functions.md - PR PR: Transform searching functions md to rst #368
• set_functions.md - PR PR: Transform set functions md to rst #369
• sorting_functions.md - PR PR: Transform sorting functions from md to rst file #333
• statistical_functions.md - PR PR: Transform statistical functions md to rst #370
• type_promotion.md - PR PR: Transform type promotion md to rst #371
• utility_functions.md - PR PR: Transform utility functions md to rst #372

Design topics

• C_API.md - PR PR: Transform C API md to rst #374
• accuracy.md - PR PR: Transform accuracy md to rst #375
• copies_views_and_mutation.md - PR PR: Transform copies views and mutation md to rst #376
• data_dependent_output_shapes.md - PR PR: Transform data dependent output shapes md to rst #377
• data_interchange.md - PR PR: Transform data interchange mechanisms md to rst #378
• device_support.md - PR PR: Transform device support md to rst #379
• parallelism.md - PR PR: Transform parallelism md to rst #380
• static_typing.md - PR PR: Transform static typing md to rst #381

Extensions

• linear_algebra_functions.md - PR PR: Transform linear algebra functions extension md to rst #384

[xloem]

idea:
specification held as python source with documented function stubs

• easy to machine-read via import
• sphinx already understands the format
• might open possible implementation avenues such as inheritance or a reference implementation

[rgommers]

specification held as python source with documented function stubs

Thanks for the suggestion @xloem. That is one of the options @steff456 is testing, it would indeed be a significant improvement over the .md files.

[xloem]

I ended up hacking some quick py file generation at https://github.com/xloem/arrays to work with the spec in the repl help(). I was thinking of making a base class for something that plugged in api implementation fudges based on name matching with existing libraries

[rgommers]

Thanks for sharing @xloem. That may be useful as an intermediate step; I'm hoping we end up with a more normal spec though which uses the numpydoc docstring format. So instead of:

Parameters
**********

*   **start**: *Union[ int, float ]*

it should look like:

Parameters
----------
start: Union[int, float]

[xloem]

The source of the sphinx builder that outputs rst probably reveals what document elements might output that format, but if it's a one-way change a search+replace tool might be simpler.

[kgryte]

@steff456 Now that this tracking issue is complete, can we close this out?

[steff456]

I'm closing this issue given that all the specification is now in rst 🎉🎉🎉