diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..0e28134f --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +*.swp +_build diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..c6267867 --- /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/01_purpose_and_scope.md b/spec/01_purpose_and_scope.md new file mode 100644 index 00000000..d7b41950 --- /dev/null +++ b/spec/01_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/02_use_cases.md b/spec/02_use_cases.md new file mode 100644 index 00000000..648f17c8 --- /dev/null +++ b/spec/02_use_cases.md @@ -0,0 +1,7 @@ +# Use cases + +## Types of use cases + + + +## Concrete use cases diff --git a/spec/03_assumptions.md b/spec/03_assumptions.md new file mode 100644 index 00000000..b7157e67 --- /dev/null +++ b/spec/03_assumptions.md @@ -0,0 +1,15 @@ +# Assumptions + +## Hardware environments + + + +## Software environments + + + +## Dependencies + + + +## Interactive use & production code diff --git a/spec/04_design_topics/backwards_compatibility.md b/spec/04_design_topics/backwards_compatibility.md new file mode 100644 index 00000000..0b94dddb --- /dev/null +++ b/spec/04_design_topics/backwards_compatibility.md @@ -0,0 +1,4 @@ +# Backwards compatibility + +This section discusses the impact on existing dataframe libraries of +choices made in the API standard, and the trade-offs that went into them. diff --git a/spec/04_design_topics/data_interchange.md b/spec/04_design_topics/data_interchange.md new file mode 100644 index 00000000..bf21592b --- /dev/null +++ b/spec/04_design_topics/data_interchange.md @@ -0,0 +1 @@ +# Data interchange mechanisms diff --git a/spec/04_design_topics/index.rst b/spec/04_design_topics/index.rst new file mode 100644 index 00000000..d78271ec --- /dev/null +++ b/spec/04_design_topics/index.rst @@ -0,0 +1,9 @@ +Design topics & constraints +=========================== + +.. toctree:: + :caption: Design topics & constraints + :maxdepth: 1 + + backwards_compatibility + data_interchange diff --git a/spec/05_future_API_evolution.md b/spec/05_future_API_evolution.md new file mode 100644 index 00000000..0c538d8a --- /dev/null +++ b/spec/05_future_API_evolution.md @@ -0,0 +1,13 @@ +# Future API standard evolution + +## Scope extensions + + + +## Backwards compatibility + + + +## Versioning + + diff --git a/spec/06_API_specification/01_dataframe_basics.md b/spec/06_API_specification/01_dataframe_basics.md new file mode 100644 index 00000000..668f564c --- /dev/null +++ b/spec/06_API_specification/01_dataframe_basics.md @@ -0,0 +1,9 @@ +# Dataframe basics + +## Class name + + +## Dataframe size + + +## Columns names diff --git a/spec/06_API_specification/02_column_selection.md b/spec/06_API_specification/02_column_selection.md new file mode 100644 index 00000000..fd70e98e --- /dev/null +++ b/spec/06_API_specification/02_column_selection.md @@ -0,0 +1 @@ +# Column selection diff --git a/spec/06_API_specification/03_filter_rows.md b/spec/06_API_specification/03_filter_rows.md new file mode 100644 index 00000000..4cd7cd01 --- /dev/null +++ b/spec/06_API_specification/03_filter_rows.md @@ -0,0 +1 @@ +# Filter rows diff --git a/spec/06_API_specification/index.rst b/spec/06_API_specification/index.rst new file mode 100644 index 00000000..d87dba63 --- /dev/null +++ b/spec/06_API_specification/index.rst @@ -0,0 +1,10 @@ +API specification +================= + +.. toctree:: + :caption: API specification + :maxdepth: 1 + + 01_dataframe_basics + 02_column_selection + 03_filter_rows diff --git a/spec/07_usage_data.md b/spec/07_usage_data.md new file mode 100644 index 00000000..9280e5c1 --- /dev/null +++ b/spec/07_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/08_verification_test_suite.md b/spec/08_verification_test_suite.md new file mode 100644 index 00000000..9ef31e19 --- /dev/null +++ b/spec/08_verification_test_suite.md @@ -0,0 +1,2 @@ +# Verification - test suite + diff --git a/spec/09_benchmark_suite.md b/spec/09_benchmark_suite.md new file mode 100644 index 00000000..77000885 --- /dev/null +++ b/spec/09_benchmark_suite.md @@ -0,0 +1 @@ +# Benchmark suite diff --git a/spec/Makefile b/spec/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /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/conf.py b/spec/conf.py new file mode 100644 index 00000000..4349032f --- /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 dataframe 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 dataframe 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/index.rst b/spec/index.rst new file mode 100644 index 00000000..8663f136 --- /dev/null +++ b/spec/index.rst @@ -0,0 +1,29 @@ +Python dataframe API standard +============================= + +Contents +-------- + +.. toctree:: + :caption: Context + :maxdepth: 1 + + 01_purpose_and_scope + 02_use_cases + 03_assumptions + +.. toctree:: + :caption: API + :maxdepth: 1 + + 04_design_topics/index + 05_future_API_evolution + 06_API_specification/index + +.. toctree:: + :caption: Methodology and Usage + :maxdepth: 1 + + 07_usage_data + 08_verification_test_suite + 09_benchmark_suite diff --git a/spec/make.bat b/spec/make.bat new file mode 100644 index 00000000..2119f510 --- /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