python reference guide

pola-rs · Aug 5, 2021 · 231bab5 · 231bab5
1 parent 49598ae
commit 231bab5
Show file tree

Hide file tree

Showing 28 changed files with 984 additions and 526 deletions.
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -24,10 +24,17 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install pdoc3 ghp-import numpy pyarrow
+          pip install -r py-polars/build.requirements.txt
+          cd py-polars && ./tasks.sh test-install
+      - name: Build python reference
+        run: |
+          cd py-polars/docs
+          make html
       - name: deploy docs
         run: |
           RUSTFLAGS="--cfg docsrs" cargo doc --all-features --package polars && \
           echo '<meta http-equiv=refresh content=0;url=polars/index.html>' > target/doc/index.html && \
+          mkdir target/doc/py-polars
+          cp -r py-polars/docs/build/html target/doc/py-polars
           ghp-import -n target/doc && \
           git push -qf https://${{ secrets.GITHUB_TOKEN }}@github.com/${GITHUB_REPOSITORY}.git gh-pages
diff --git a/README.md b/README.md
@@ -41,21 +41,13 @@ Install the latest polars version with:
 Want to know about all the features Polars support? Read the docs!
 
 #### Rust
-* [Documentation (stable)](https://docs.rs/polars/latest/polars/). 
 * [Documentation (master branch)](https://pola-rs.github.io/polars/polars/index.html). 
-    * [DataFrame](https://pola-rs.github.io/polars/polars/frame/struct.DataFrame.html) 
-    * [Series](https://pola-rs.github.io/polars/polars/prelude/struct.Series.html)
-    * [ChunkedArray](https://pola-rs.github.io/polars/polars/chunked_array/struct.ChunkedArray.html)
-    * [Traits for ChunkedArray](https://pola-rs.github.io/polars/polars/chunked_array/ops/index.html)
-    * [Time/ DateTime utilities](https://pola-rs.github.io/polars/polars/doc/time/index.html)
-    * [Groupby, aggregations and pivots](https://pola-rs.github.io/polars/polars/frame/groupby/struct.GroupBy.html)
-    * [Lazy DataFrame](https://pola-rs.github.io/polars/polars/prelude/struct.LazyFrame.html)
 * [User Guide](https://pola-rs.github.io/polars-book/)
 
 #### Python
 * installation guide: `$ pip3 install polars`
 * [User Guide](https://pola-rs.github.io/polars-book/)
-* [Reference guide](https://pola-rs.github.io/polars-book/api-python/)
+* [Reference guide](https://pola-rs.github.io/polars/py-polars/html/reference/index.html)
 
 ## Contribution
 Want to contribute? Read our [contribution guideline](https://github.com/ritchie46/polars/blob/master/CONTRIBUTING.md).

diff --git a/py-polars/.flake8 b/py-polars/.flake8
@@ -3,5 +3,5 @@
 max-line-length = 180
 # E203, W504: due to black fmt
 ignore = E203,W503
-exclude = tests, legacy
+exclude = tests, legacy, docs
 
diff --git a/py-polars/build.requirements.txt b/py-polars/build.requirements.txt
@@ -4,6 +4,19 @@ black==21.6b0
 isort~=5.9.2
 mypy~=0.910
 numpy
+pyarrow
 ghp-import
 pandas
 flake8
+sphinx
+pydata-sphinx-theme==0.6.3
+sphinx-panels==0.6.0
+sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.0
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-napoleon
+commonmark==0.9.1
+
diff --git a/py-polars/docs/.gitignore b/py-polars/docs/.gitignore
@@ -0,0 +1,3 @@
+build/
+pandas/
+source/reference/api/
diff --git a/py-polars/docs/Makefile b/py-polars/docs/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     = source
+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/py-polars/docs/_templates/api_redirect.html b/py-polars/docs/_templates/api_redirect.html
@@ -0,0 +1,10 @@
+{% set redirect = redirects[pagename.split("/")[-1]] %}
+<html>
+    <head>
+        <meta http-equiv="Refresh" content="0; url={{ redirect }}.html" />
+        <title>This API page has moved</title>
+    </head>
+    <body>
+        <p>This API page has moved <a href="{{ redirect }}.html">here</a>.</p>
+    </body>
+</html>
diff --git a/py-polars/docs/_templates/autosummary/accessor.rst b/py-polars/docs/_templates/autosummary/accessor.rst
@@ -0,0 +1,6 @@
+{{ fullname }}
+{{ underline }}
+
+.. currentmodule:: {{ module.split('.')[0] }}
+
+.. autoaccessor:: {{ (module.split('.')[1:] + [objname]) | join('.') }}
diff --git a/py-polars/docs/_templates/autosummary/accessor_attribute.rst b/py-polars/docs/_templates/autosummary/accessor_attribute.rst
@@ -0,0 +1,6 @@
+{{ fullname }}
+{{ underline }}
+
+.. currentmodule:: {{ module.split('.')[0] }}
+
+.. autoaccessorattribute:: {{ (module.split('.')[1:] + [objname]) | join('.') }}
diff --git a/py-polars/docs/_templates/autosummary/accessor_callable.rst b/py-polars/docs/_templates/autosummary/accessor_callable.rst
@@ -0,0 +1,6 @@
+{{ fullname }}
+{{ underline }}
+
+.. currentmodule:: {{ module.split('.')[0] }}
+
+.. autoaccessorcallable:: {{ (module.split('.')[1:] + [objname]) | join('.') }}.__call__
diff --git a/py-polars/docs/_templates/autosummary/accessor_method.rst b/py-polars/docs/_templates/autosummary/accessor_method.rst
@@ -0,0 +1,6 @@
+{{ fullname }}
+{{ underline }}
+
+.. currentmodule:: {{ module.split('.')[0] }}
+
+.. autoaccessormethod:: {{ (module.split('.')[1:] + [objname]) | join('.') }}
diff --git a/py-polars/docs/_templates/autosummary/class.rst b/py-polars/docs/_templates/autosummary/class.rst
@@ -0,0 +1,33 @@
+{% extends "!autosummary/class.rst" %}
+
+{% block methods %}
+{% if methods %}
+
+..
+   HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+   .. autosummary::
+      :toctree:
+      {% for item in all_methods %}
+      {%- if not item.startswith('_') or item in ['__call__'] %}
+      {{ name }}.{{ item }}
+      {%- endif -%}
+      {%- endfor %}
+
+{% endif %}
+{% endblock %}
+
+{% block attributes %}
+{% if attributes %}
+
+..
+   HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+   .. autosummary::
+      :toctree:
+      {% for item in all_attributes %}
+      {%- if not item.startswith('_') %}
+      {{ name }}.{{ item }}
+      {%- endif -%}
+      {%- endfor %}
+
+{% endif %}
+{% endblock %}
diff --git a/py-polars/docs/_templates/autosummary/class_without_autosummary.rst b/py-polars/docs/_templates/autosummary/class_without_autosummary.rst
@@ -0,0 +1,6 @@
+{{ fullname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
diff --git a/py-polars/docs/_templates/sidebar-nav-bs.html b/py-polars/docs/_templates/sidebar-nav-bs.html
@@ -0,0 +1,9 @@
+<nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">
+  <div class="bd-toc-item active">
+    {% if pagename.startswith("reference") %}
+    {{ generate_nav_html("sidebar", maxdepth=4, collapse=True, includehidden=True, titles_only=True) }}
+    {% else %}
+    {{ generate_nav_html("sidebar", maxdepth=4, collapse=False, includehidden=True, titles_only=True) }}
+    {% endif %}
+  </div>
+</nav>
diff --git a/py-polars/docs/source/conf.py b/py-polars/docs/source/conf.py
@@ -0,0 +1,99 @@
+# 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('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "Polars"
+copyright = "2021, Ritchie Vink"
+author = "Ritchie Vink"
+
+
+# -- 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 = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.doctest",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.todo",
+    "sphinx.ext.napoleon",  # numpy docstrings
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.ifconfig",
+    "sphinx_panels",
+]
+
+# 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 = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+# html_theme = 'alabaster'
+html_theme = "pydata_sphinx_theme"
+
+# 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"]
+
+html_logo = "../img/polars_logo.png"
+autosummary_generate = True
+
+html_theme_options = {
+    "external_links": [
+        {
+            "name": "User Guide",
+            "url": "https://pola-rs.github.io/polars-book/user-guide/index.html",
+        },
+        {"name": "Powered by Xomnia", "url": "https://www.xomnia.com/"},
+    ],
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/pola-rs/polars",
+            "icon": "fab fa-github-square",
+        },
+    ],
+}
+
+# for markdown in docstring
+import commonmark
+
+
+def docstring(app, what, name, obj, options, lines):
+    md = "\n".join(lines)
+    ast = commonmark.Parser().parse(md)
+    rst = commonmark.ReStructuredTextRenderer().render(ast)
+    lines.clear()
+    lines += rst.splitlines()
+
+
+def setup(app):
+    app.connect("autodoc-process-docstring", docstring)
diff --git a/py-polars/docs/source/index.rst b/py-polars/docs/source/index.rst
@@ -0,0 +1,6 @@
+
+.. toctree::
+   :maxdepth: 2
+
+   reference/index
+