diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..8a251964d --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +spec/_build/ diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 000000000..c6267867c --- /dev/null +++ b/requirements.txt @@ -0,0 +1,5 @@ +sphinx==3.1.1 +sphinx-material==0.0.30 +recommonmark +sphinx_markdown_tables +sphinx_copybutton diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md new file mode 100644 index 000000000..07e4f0850 --- /dev/null +++ b/spec/API_specification/array_object.md @@ -0,0 +1 @@ +# Array object diff --git a/spec/API_specification/casting.md b/spec/API_specification/casting.md new file mode 100644 index 000000000..658b457a8 --- /dev/null +++ b/spec/API_specification/casting.md @@ -0,0 +1 @@ +# Dtype casting diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst new file mode 100644 index 000000000..524cc2267 --- /dev/null +++ b/spec/API_specification/index.rst @@ -0,0 +1,10 @@ +API specification +================= + +.. toctree:: + :caption: API specification + :maxdepth: 1 + + array_object + indexing + casting diff --git a/spec/API_specification/indexing.md b/spec/API_specification/indexing.md new file mode 100644 index 000000000..8a838b459 --- /dev/null +++ b/spec/API_specification/indexing.md @@ -0,0 +1 @@ +# Indexing diff --git a/spec/Makefile b/spec/Makefile new file mode 100644 index 000000000..d4bb2cbb9 --- /dev/null +++ b/spec/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/spec/assumptions.md b/spec/assumptions.md new file mode 100644 index 000000000..b7157e67d --- /dev/null +++ b/spec/assumptions.md @@ -0,0 +1,15 @@ +# Assumptions + +## Hardware environments + + + +## Software environments + + + +## Dependencies + + + +## Interactive use & production code diff --git a/spec/benchmark_suite.md b/spec/benchmark_suite.md new file mode 100644 index 000000000..770008857 --- /dev/null +++ b/spec/benchmark_suite.md @@ -0,0 +1 @@ +# Benchmark suite diff --git a/spec/conf.py b/spec/conf.py new file mode 100644 index 000000000..8f0bc313c --- /dev/null +++ b/spec/conf.py @@ -0,0 +1,160 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +import sphinx_material +from recommonmark.transform import AutoStructify + +# -- Project information ----------------------------------------------------- + +project = 'Python array API standard' +copyright = '2020, Consortium for Python Data API Standards' +author = 'Consortium for Python Data API Standards' + +# The full version, including alpha/beta/rc tags +release = '0.1-dev' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'recommonmark', + 'sphinx.ext.extlinks', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx_markdown_tables', + 'sphinx_copybutton', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +extensions.append("sphinx_material") +html_theme_path = sphinx_material.html_theme_path() +html_context = sphinx_material.get_html_context() +html_theme = 'sphinx_material' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + + +# -- Material theme options (see theme.conf for more information) ------------ +html_show_sourcelink = False +html_sidebars = { + "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"] +} + +html_theme_options = { + + # Set the name of the project to appear in the navigation. + 'nav_title': 'Python array API standard', + + # Set you GA account ID to enable tracking + #'google_analytics_account': 'UA-XXXXX', + + # Specify a base_url used to generate sitemap.xml. If not + # specified, then no sitemap will be built. + #'base_url': 'https://project.github.io/project', + + # Set the color and the accent color (see + # https://material.io/design/color/the-color-system.html) + 'color_primary': 'deep-purple', + 'color_accent': 'cyan', + + # Set the repo location to get a badge with stats + #'repo_url': 'https://github.com/project/project/', + #'repo_name': 'Project', + + "html_minify": False, + "html_prettify": True, + "css_minify": True, + "logo_icon": "", + "repo_type": "github", + "touch_icon": "images/apple-icon-152x152.png", + "theme_color": "#2196f3", + "master_doc": False, + + # Visible levels of the global TOC; -1 means unlimited + 'globaltoc_depth': 2, + # If False, expand all TOC entries + 'globaltoc_collapse': True, + # If True, show hidden TOC entries + 'globaltoc_includehidden': True, + + "nav_links": [ + {"href": "index", "internal": True, "title": "Array API standard"}, + { + "href": "https://link-to-consortium-website", + "internal": False, + "title": "Consortium for Python Data API Standards", + }, + ], + "heroes": { + "index": "A common API for array and tensor Python libraries", + #"customization": "Configuration options to personalize your site.", + }, + + #"version_dropdown": True, + #"version_json": "_static/versions.json", + "table_classes": ["plain"], +} + + +todo_include_todos = True +#html_favicon = "images/favicon.ico" + +html_use_index = True +html_domain_indices = True + +extlinks = { + "duref": ( + "http://docutils.sourceforge.net/docs/ref/rst/" "restructuredtext.html#%s", + "", + ), + "durole": ("http://docutils.sourceforge.net/docs/ref/rst/" "roles.html#%s", ""), + "dudir": ("http://docutils.sourceforge.net/docs/ref/rst/" "directives.html#%s", ""), +} + + +# Enable eval_rst in markdown +def setup(app): + app.add_config_value( + "recommonmark_config", + {"enable_math": True, "enable_inline_math": True, "enable_eval_rst": True}, + True, + ) + app.add_transform(AutoStructify) + app.add_object_type( + "confval", + "confval", + objname="configuration value", + indextemplate="pair: %s; configuration value", + ) diff --git a/spec/design_topics/C_API.md b/spec/design_topics/C_API.md new file mode 100644 index 000000000..89586d4d8 --- /dev/null +++ b/spec/design_topics/C_API.md @@ -0,0 +1 @@ +# C API diff --git a/spec/design_topics/array_ducktyping.md b/spec/design_topics/array_ducktyping.md new file mode 100644 index 000000000..148ebceae --- /dev/null +++ b/spec/design_topics/array_ducktyping.md @@ -0,0 +1 @@ +# Array duck typing diff --git a/spec/design_topics/backwards_compatibility.md b/spec/design_topics/backwards_compatibility.md new file mode 100644 index 000000000..b24080776 --- /dev/null +++ b/spec/design_topics/backwards_compatibility.md @@ -0,0 +1,4 @@ +# Backwards compatibility + +This section discusses the impact on existing array and tensor libraries of +choices made in the API standard, and the trade-offs that went into them. diff --git a/spec/design_topics/data_interchange.md b/spec/design_topics/data_interchange.md new file mode 100644 index 000000000..bf21592ba --- /dev/null +++ b/spec/design_topics/data_interchange.md @@ -0,0 +1 @@ +# Data interchange mechanisms diff --git a/spec/design_topics/eager_lazy_eval.md b/spec/design_topics/eager_lazy_eval.md new file mode 100644 index 000000000..e52743b98 --- /dev/null +++ b/spec/design_topics/eager_lazy_eval.md @@ -0,0 +1 @@ +# Eager and lazy evaluation diff --git a/spec/design_topics/index.rst b/spec/design_topics/index.rst new file mode 100644 index 000000000..c481e0d9e --- /dev/null +++ b/spec/design_topics/index.rst @@ -0,0 +1,16 @@ +Design topics & constraints +=========================== + +.. toctree:: + :caption: Design topics & constraints + :maxdepth: 1 + + backwards_compatibility + eager_lazy_eval + parallelism + static_typing + array_ducktyping + data_interchange + missing_data + portability + C_API diff --git a/spec/design_topics/missing_data.md b/spec/design_topics/missing_data.md new file mode 100644 index 000000000..77c88f7eb --- /dev/null +++ b/spec/design_topics/missing_data.md @@ -0,0 +1 @@ +# Missing data diff --git a/spec/design_topics/parallelism.md b/spec/design_topics/parallelism.md new file mode 100644 index 000000000..5c3fb8484 --- /dev/null +++ b/spec/design_topics/parallelism.md @@ -0,0 +1 @@ +# Parallelism diff --git a/spec/design_topics/portability.md b/spec/design_topics/portability.md new file mode 100644 index 000000000..55e0a0f6d --- /dev/null +++ b/spec/design_topics/portability.md @@ -0,0 +1 @@ +# Portability diff --git a/spec/design_topics/static_typing.md b/spec/design_topics/static_typing.md new file mode 100644 index 000000000..ee3df101f --- /dev/null +++ b/spec/design_topics/static_typing.md @@ -0,0 +1 @@ +# Static typing diff --git a/spec/future_API_evolution.md b/spec/future_API_evolution.md new file mode 100644 index 000000000..0c538d8af --- /dev/null +++ b/spec/future_API_evolution.md @@ -0,0 +1,13 @@ +# Future API standard evolution + +## Scope extensions + + + +## Backwards compatibility + + + +## Versioning + + diff --git a/spec/index.rst b/spec/index.rst new file mode 100644 index 000000000..aaf20aeec --- /dev/null +++ b/spec/index.rst @@ -0,0 +1,34 @@ +.. Python array API standard documentation master file, created by + sphinx-quickstart on Mon Jun 15 16:55:00 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Python array API standard +========================= + +Contents +-------- + +.. toctree:: + :caption: Context + :maxdepth: 1 + + purpose_and_scope + use_cases + assumptions + +.. toctree:: + :caption: API + :maxdepth: 1 + + design_topics/index + future_API_evolution + API_specification/index + +.. toctree:: + :caption: Methodology and Usage + :maxdepth: 1 + + usage_data + verification_test_suite + benchmark_suite diff --git a/spec/make.bat b/spec/make.bat new file mode 100644 index 000000000..2119f5109 --- /dev/null +++ b/spec/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md new file mode 100644 index 000000000..d7b419504 --- /dev/null +++ b/spec/purpose_and_scope.md @@ -0,0 +1,41 @@ +# Purpose and scope + +## Introduction + + + +## History + + + +## Scope (includes out-of-scope / non-goals) + + + +## Stakeholders + + + + +## High-level API overview + + + + +## How to read this document + + + + +## How to adopt this API + + + + +## Definitions + + + + +## References + diff --git a/spec/usage_data.md b/spec/usage_data.md new file mode 100644 index 000000000..9280e5c13 --- /dev/null +++ b/spec/usage_data.md @@ -0,0 +1,17 @@ +# Data on existing API design & usage + +## Summary + + + + +## Methods + + + + +## Tooling + + + +## Detailed results and raw data diff --git a/spec/use_cases.md b/spec/use_cases.md new file mode 100644 index 000000000..648f17c8a --- /dev/null +++ b/spec/use_cases.md @@ -0,0 +1,7 @@ +# Use cases + +## Types of use cases + + + +## Concrete use cases diff --git a/spec/verification_test_suite.md b/spec/verification_test_suite.md new file mode 100644 index 000000000..9ef31e190 --- /dev/null +++ b/spec/verification_test_suite.md @@ -0,0 +1,2 @@ +# Verification - test suite +