apply ppt

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 LINCC Frameworks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

benchmarks/asv.conf.json

@@ -0,0 +1,80 @@
+{
+    // The version of the config file format. Do not change, unless
+    // you know what you are doing.
+    "version": 1,
+    // The name of the project being benchmarked.
+    "project": "nested-pandas",
+    // The project's homepage.
+    "project_url": "https://github.com/lincc-frameworks/nested-pandas",
+    // The URL or local path of the source code repository for the
+    // project being benchmarked.
+    "repo": "..",
+    // List of branches to benchmark. If not provided, defaults to "master"
+    // (for git) or "tip" (for mercurial).
+    "branches": [
+        "HEAD"
+    ],
+    "install_command": [
+        "python -m pip install {wheel_file}"
+    ],
+    "build_command": [
+        "python -m build --wheel -o {build_cache_dir} {build_dir}"
+    ],
+    // The DVCS being used. If not set, it will be automatically
+    // determined from "repo" by looking at the protocol in the URL
+    // (if remote), or by looking for special directories, such as
+    // ".git" (if local).
+    "dvcs": "git",
+    // The tool to use to create environments. May be "conda",
+    // "virtualenv" or other value depending on the plugins in use.
+    // If missing or the empty string, the tool will be automatically
+    // determined by looking for tools on the PATH environment
+    // variable.
+    "environment_type": "virtualenv",
+    // the base URL to show a commit for the project.
+    "show_commit_url": "https://github.com/lincc-frameworks/nested-pandas/commit/",
+    // The Pythons you'd like to test against. If not provided, defaults
+    // to the current version of Python used to run `asv`.
+    "pythons": [
+        "3.10"
+    ],
+    // The matrix of dependencies to test. Each key is the name of a
+    // package (in PyPI) and the values are version numbers.  An empty
+    // list indicates to just test against the default (latest)
+    // version.
+    "matrix": {
+        "Cython": [],
+        "build": [],
+        "packaging": []
+    },
+    // The directory (relative to the current directory) that benchmarks are
+    // stored in. If not provided, defaults to "benchmarks".
+    "benchmark_dir": ".",
+    // The directory (relative to the current directory) to cache the Python
+    // environments in. If not provided, defaults to "env".
+    "env_dir": "env",
+    // The directory (relative to the current directory) that raw benchmark
+    // results are stored in. If not provided, defaults to "results".
+    "results_dir": "_results",
+    // The directory (relative to the current directory) that the html tree
+    // should be written to. If not provided, defaults to "html".
+    "html_dir": "_html",
+    // The number of characters to retain in the commit hashes.
+    // "hash_length": 8,
+    // `asv` will cache wheels of the recent builds in each
+    // environment, making them faster to install next time. This is
+    // number of builds to keep, per environment.
+    "build_cache_size": 8
+    // The commits after which the regression search in `asv publish`
+    // should start looking for regressions. Dictionary whose keys are
+    // regexps matching to benchmark names, and values corresponding to
+    // the commit (exclusive) after which to start looking for
+    // regressions. The default is to start from the first commit
+    // with results. If the commit is `null`, regression detection is
+    // skipped for the matching benchmark.
+    //
+    // "regressions_first_commits": {
+    //    "some_benchmark": "352cdf",  // Consider regressions only after this commit
+    //    "another_benchmark": null,   // Skip regression detection altogether
+    // }
+}

benchmarks/benchmarks.py

@@ -0,0 +1,16 @@
+"""Two sample benchmarks to compute runtime and memory usage.
+
+For more information on writing benchmarks:
+https://asv.readthedocs.io/en/stable/writing_benchmarks.html."""
+
+from nested_pandas import example_benchmarks
+
+
+def time_computation():
+    """Time computations are prefixed with 'time'."""
+    example_benchmarks.runtime_computation()
+
+
+def mem_list():
+    """Memory computations are prefixed with 'mem' or 'peakmem'."""
+    return example_benchmarks.memory_computation()

docs/Makefile

@@ -0,0 +1,31 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -T -E -d _build/doctrees -D language=en
+EXCLUDENB     ?= -D exclude_patterns="notebooks/*","_build","**.ipynb_checkpoints"
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = ../_readthedocs/
+
+.PHONY: help clean Makefile no-nb no-notebooks
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Build all Sphinx docs locally, except the notebooks
+no-nb no-notebooks:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(EXCLUDENB) $(O)
+
+# Cleans up files generated by the build process
+clean:
+	rm -r "_build/doctrees"
+	rm -r "$(BUILDDIR)"
+
+# 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)
+

docs/conf.py

@@ -0,0 +1,58 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+
+import os
+import sys
+from importlib.metadata import version
+
+# Define path to the code to be documented **relative to where conf.py (this file) is kept**
+sys.path.insert(0, os.path.abspath("../src/"))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "nested-pandas"
+copyright = "2023, LINCC Frameworks"
+author = "LINCC Frameworks"
+release = version("nested-pandas")
+# for example take major/minor
+version = ".".join(release.split(".")[:2])
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["sphinx.ext.mathjax", "sphinx.ext.napoleon", "sphinx.ext.viewcode"]
+
+extensions.append("autoapi.extension")
+extensions.append("nbsphinx")
+
+# -- sphinx-copybutton configuration ----------------------------------------
+extensions.append("sphinx_copybutton")
+## sets up the expected prompt text from console blocks, and excludes it from
+## the text that goes into the clipboard.
+copybutton_exclude = ".linenos, .gp"
+copybutton_prompt_text = ">> "
+
+## lets us suppress the copy button on select code blocks.
+copybutton_selector = "div:not(.no-copybutton) > div.highlight > pre"
+
+templates_path = []
+exclude_patterns = ["_build", "**.ipynb_checkpoints"]
+
+# This assumes that sphinx-build is called from the root directory
+master_doc = "index"
+# Remove 'view source code' from top of page (for html, not python)
+html_show_sourcelink = False
+# Remove namespaces from class/method signatures
+add_module_names = False
+
+autoapi_type = "python"
+autoapi_dirs = ["../src"]
+autoapi_ignore = ["*/__main__.py", "*/_version.py"]
+autoapi_add_toc_tree_entry = False
+autoapi_member_order = "bysource"
+
+html_theme = "sphinx_rtd_theme"

docs/index.rst

@@ -0,0 +1,50 @@
+.. nested_pandas documentation main file.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to nested_pandas's documentation!
+========================================================================================
+
+Dev Guide - Getting Started
+---------------------------
+
+Before installing any dependencies or writing code, it's a great idea to create a
+virtual environment. LINCC-Frameworks engineers primarily use `conda` to manage virtual
+environments. If you have conda installed locally, you can run the following to
+create and activate a new environment.
+
+.. code-block:: console
+
+   >> conda create env -n <env_name> python=3.10
+   >> conda activate <env_name>
+
+
+Once you have created a new environment, you can install this project for local
+development using the following commands:
+
+.. code-block:: console
+
+   >> pip install -e .'[dev]'
+   >> pre-commit install
+   >> conda install pandoc
+
+
+Notes:
+
+1) The single quotes around ``'[dev]'`` may not be required for your operating system.
+2) ``pre-commit install`` will initialize pre-commit for this local repository, so
+   that a set of tests will be run prior to completing a local commit. For more
+   information, see the Python Project Template documentation on
+   `pre-commit <https://lincc-ppt.readthedocs.io/en/latest/practices/precommit.html>`_.
+3) Installing ``pandoc`` allows you to verify that automatic rendering of Jupyter notebooks
+   into documentation for ReadTheDocs works as expected. For more information, see
+   the Python Project Template documentation on
+   `Sphinx and Python Notebooks <https://lincc-ppt.readthedocs.io/en/latest/practices/sphinx.html#python-notebooks>`_.
+
+
+.. toctree::
+   :hidden:
+
+   Home page <self>
+   API Reference <autoapi/index>
+   Notebooks <notebooks>

docs/notebooks.rst

@@ -0,0 +1,6 @@
+Notebooks
+========================================================================================
+
+.. toctree::
+
+    Introducing Jupyter Notebooks <notebooks/intro_notebook>

docs/notebooks/README.md

@@ -0,0 +1 @@
+Put your Jupyter notebooks here :)

docs/notebooks/intro_notebook.ipynb

@@ -0,0 +1,84 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "textblock1",
+   "metadata": {
+    "cell_marker": "\"\"\""
+   },
+   "source": [
+    "# Introducing Jupyter Notebooks in Sphinx\n",
+    "\n",
+    "This notebook showcases very basic functionality of rendering your jupyter notebooks as tutorials inside your sphinx documentation.\n",
+    "\n",
+    "As part of the LINCC Frameworks python project template, your notebooks will be executed AND rendered at document build time.\n",
+    "\n",
+    "You can read more about Sphinx, ReadTheDocs, and building notebooks in [LINCC's documentation](https://lincc-ppt.readthedocs.io/en/latest/practices/sphinx.html)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "codeblock1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def sierpinsky(order):\n",
+    "    \"\"\"Define a method that will create a Sierpinsky triangle of given order,\n",
+    "    and will print it out.\"\"\"\n",
+    "    triangles = [\"*\"]\n",
+    "    for i in range(order):\n",
+    "        spaces = \" \" * (2**i)\n",
+    "        triangles = [spaces + triangle + spaces for triangle in triangles] + [\n",
+    "            triangle + \" \" + triangle for triangle in triangles\n",
+    "        ]\n",
+    "    print(f\"Printing order {order} triangle\")\n",
+    "    print(\"\\n\".join(triangles))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "textblock2",
+   "metadata": {
+    "cell_marker": "\"\"\"",
+    "lines_to_next_cell": 1
+   },
+   "source": [
+    "Then, call our method a few times. This will happen on the fly during notebook rendering."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "codeblock2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for order in range(3):\n",
+    "    sierpinsky(order)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "codeblock3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sierpinsky(4)"
+   ]
+  }
+ ],
+ "metadata": {
+  "jupytext": {
+   "cell_markers": "\"\"\""
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/requirements.txt

@@ -0,0 +1,10 @@
+
+ipykernel
+ipython
+jupytext
+nbconvert
+nbsphinx
+sphinx
+sphinx-autoapi
+sphinx-copybutton
+sphinx-rtd-theme