Initial commit

docs/source/CHANGELOG.md

@@ -0,0 +1 @@
+../../CHANGELOG.md

docs/source/CONTRIBUTING.md

@@ -0,0 +1 @@
+../../CONTRIBUTING.md

docs/source/conf.py

@@ -0,0 +1,121 @@
+# 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
+
+import logging
+import os
+import sys
+from datetime import datetime
+
+# -- 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.
+#
+
+sys.path.insert(0, os.path.abspath("../../"))
+
+from my_package.version import VERSION, VERSION_SHORT  # noqa: E402
+
+# -- Project information -----------------------------------------------------
+
+project = "my-package"
+copyright = f"{datetime.today().year}, Allen Institute for Artificial Intelligence"
+author = "Allen Institute for Artificial Intelligence"
+version = VERSION_SHORT
+release = VERSION
+
+
+# -- 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.napoleon",
+    "myst_parser",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.doctest",
+    "sphinx_copybutton",
+    "sphinx_autodoc_typehints",
+]
+
+# Tell myst-parser to assign header anchors for h1-h3.
+myst_heading_anchors = 3
+
+suppress_warnings = ["myst.header"]
+
+# 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"]
+
+source_suffix = [".rst", ".md"]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    # Uncomment these if you use them in your codebase:
+    #  "torch": ("https://pytorch.org/docs/stable", None),
+    #  "datasets": ("https://huggingface.co/docs/datasets/master/en", None),
+    #  "transformers": ("https://huggingface.co/docs/transformers/master/en", None),
+}
+
+# By default, sort documented members by type within classes and modules.
+autodoc_member_order = "groupwise"
+
+# Include default values when documenting parameter types.
+typehints_defaults = "comma"
+
+
+# -- 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 = "furo"
+
+html_title = f"my-package v{VERSION}"
+
+# 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_css_files = ["css/custom.css"]
+
+html_favicon = "_static/favicon.ico"
+
+html_theme_options = {
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/allenai/python-package-template",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,  # noqa: E501
+            "class": "",
+        },
+    ],
+}
+
+# -- Hack to get rid of stupid warnings from sphinx_autodoc_typehints --------
+
+
+class ShutupSphinxAutodocTypehintsFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        if "Cannot resolve forward reference" in record.msg:
+            return False
+        return True
+
+
+logging.getLogger("sphinx.sphinx_autodoc_typehints").addFilter(ShutupSphinxAutodocTypehintsFilter())

docs/source/index.rst

@@ -0,0 +1,49 @@
+.. my_package documentation master file, created by
+   sphinx-quickstart on Tue Sep 21 08:07:48 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+**my-package**
+===============
+
+.. automodule:: my_package
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting started:
+
+   installation
+   overview
+   CHANGELOG
+
+.. toctree::
+   :hidden:
+   :caption: Development
+
+   License <https://raw.githubusercontent.com/allenai/python-package-template/main/LICENSE>
+   CONTRIBUTING
+   GitHub Repository <https://github.com/allenai/python-package-template>
+
+Team
+----
+
+**my-package** is developed and maintained by the AllenNLP team, backed by
+`the Allen Institute for Artificial Intelligence (AI2) <https://allenai.org/>`_.
+AI2 is a non-profit institute with the mission to contribute to humanity through high-impact AI research and engineering.
+To learn more about who specifically contributed to this codebase, see
+`our contributors <https://github.com/allenai/python-package-template/graphs/contributors>`_ page.
+
+License
+-------
+
+**my-package** is licensed under `Apache 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`_.
+A full copy of the license can be found `on GitHub <https://github.com/allenai/python-package-template/blob/main/LICENSE>`_.
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`

docs/source/installation.md

@@ -0,0 +1,27 @@
+Installation
+============
+
+**my-package** supports Python >= 3.7.
+
+## Installing with `pip`
+
+**my-package** is available [on PyPI](https://pypi.org/project/my-package/). Just run
+
+```bash
+pip install my-package
+```
+
+## Installing from source
+
+To install **my-package** from source, first clone [the repository](https://github.com/allenai/python-package-template):
+
+```bash
+git clone https://github.com/allenai/python-package-template.git
+cd python-package-template
+```
+
+Then run
+
+```bash
+pip install -e .
+```

docs/source/overview.md

@@ -0,0 +1,3 @@
+Overview
+========
+