Start writing the readthedocs. (#101)

* Start writing the readthedocs.

* Writing.

* Writing.

* Can't get the sidebar right.

* Determining documentation organization.

* Generating documentation for all the docstrings; need to fix many warnings.

* Touching up the front page a little.

* Fixed all Sphinx warnings.

* Report is now a regular class that can be documented.

* Writing.

* Writing.

* Writing.

* Writing.

* Finished the 'Getting started guide'.

.gitignore

@@ -1,3 +1,9 @@
+# Sphinx documentation
+docs-sphinx/_build
+docs-sphinx/uproot4.rst
+docs-sphinx/uproot4.*.rst
+docs-sphinx/*.toctree
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

.readthedocs.yml

@@ -0,0 +1,9 @@
+version: 2
+
+sphinx:
+  configuration: docs-sphinx/conf.py
+
+python:
+  version: 3.7
+  install:
+    - requirements: docs-sphinx/requirements.txt

README.md

@@ -33,11 +33,19 @@ Note that Uproot 3 returns old-style [Awkward 0](https://github.com/scikit-hep/a
 
 # Installation
 
-Install uproot like any other Python package:
+Usually, you'll want to install Uproot with `Awkward Array <https://awkward-array.org>`__ because this is the default array format.
 
-```bash
-pip install uproot     # maybe with sudo or --user, -U to update, or in venv
-```
+.. code-block:: bash
+
+    pip install uproot4 awkward1
+
+But if you are working in a limited environment, Uproot can be installed without Awkward Array.
+
+.. code-block:: bash
+
+    pip install uproot4
+
+Just be sure to pass ``library="np"`` to any function that returns arrays to specify that you want NumPy arrays, rather than Awkward arrays. Other array libraries include `Pandas <https://pandas.pydata.org/>`__ and `CuPy <https://cupy.dev/>`__, which, like Awkward, would need to be explicitly installed.
 
 # Dependencies
 

docs-sphinx/conf.py

@@ -0,0 +1,57 @@
+# 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 = "Uproot"
+copyright = "2020, Jim Pivarski"
+author = "Jim Pivarski"
+
+# -- 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"]
+
+# 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.
+#
+html_theme = "sphinx_rtd_theme"
+html_logo = "../docs-img/logo/logo-300px-white.png"
+html_show_sourcelink = False
+html_theme_options = {"logo_only": True, "sticky_navigation": False}
+
+# 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"
+
+# Additional stuff
+master_doc = "index"
+
+exec(open("prepare_docstrings.py").read(), dict(globals()))
+# exec(open("make_changelog.py").read(), dict(globals()))

docs-sphinx/index.rst

@@ -0,0 +1,91 @@
+.. toctree::
+    :caption: Tutorials
+    :hidden:
+
+    basic
+    uproot3-to-4
+
+.. include:: uproot4.toctree
+
+.. include:: uproot4.reading.toctree
+
+.. include:: uproot4.behaviors.toctree
+
+.. include:: uproot4.model.toctree
+
+.. include:: uproot4.streamers.toctree
+
+.. include:: uproot4.cache.toctree
+
+.. include:: uproot4.compression.toctree
+
+.. include:: uproot4.deserialization.toctree
+
+.. include:: uproot4.source.toctree
+
+.. include:: uproot4.interpretation.toctree
+
+.. include:: uproot4.containers.toctree
+
+.. include:: uproot4.language.toctree
+
+.. include:: uproot4.models.toctree
+
+.. include:: uproot4.const.toctree
+
+.. include:: uproot4.extras.toctree
+
+.. include:: uproot4.version.toctree
+
+.. toctree::
+    :hidden:
+
+    uproot4.dynamic
+
+.. |br| raw:: html
+
+    <br/>
+
+.. image:: https://github.com/scikit-hep/uproot4/raw/master/docs-img/logo/logo-300px.png
+    :width: 300px
+    :alt: Uproot
+
+|br| Uproot is a library for reading (and soon, writing) ROOT files in pure Python and NumPy.
+
+How to install
+==============
+
+Usually, you'll want to install Uproot with `Awkward Array <https://awkward-array.org>`__ because this is the default array format.
+
+.. code-block:: bash
+
+    pip install uproot4 awkward1
+
+But if you are working in a limited environment, Uproot can be installed without Awkward Array.
+
+.. code-block:: bash
+
+    pip install uproot4
+
+Just be sure to pass ``library="np"`` to any function that returns arrays to specify that you want NumPy arrays, rather than Awkward arrays. Other array libraries include `Pandas <https://pandas.pydata.org/>`__ and `CuPy <https://cupy.dev/>`__, which, like Awkward, would need to be explicitly installed.
+
+Documentation
+=============
+
+**ROOT** is a C++ toolkit for data analysis, part of which is the ROOT file format. Over an exabyte of particle physics data are stored in ROOT files around the world.
+
+**Uproot** is a Python implementation of ROOT I/O, independent of the ROOT toolkit itself (including ROOT's Python interface, PyROOT).
+
+- If you need help understanding ROOT and its ecosystem, see the `ROOT project documentation <https://root.cern/get_started/>`__.
+- If you know what a ROOT file is but are unfamiliar with Uproot, see the :doc:`basic`.
+- If you are migrating from an older version to Uproot 4, see the :doc:`uproot3-to-4`.
+- If you need detailed descriptions of a class's properties or a function's parameters, see the left-bar on this site (≡ button on mobile) or use ``help`` in Python, ``?`` or shift-tab in iPython/Jupyter.
+
+Getting help
+============
+
+Report bugs, request features, and ask for additional documentation on `GitHub Issues <https://github.com/scikit-hep/uproot4/issues>`__.
+
+If you have a problem that's too specific to be new documentation or it isn't exclusively related to Uproot, it might be more appropriate to ask on `StackOverflow with the [uproot] tag <https://stackoverflow.com/questions/tagged/uproot>`__. Be sure to include tags for any other libraries that you use, such as boost-histogram or Pandas.
+
+The `Gitter Scikit-HEP/community <https://gitter.im/Scikit-HEP/community>`__ is a way to get in touch with all Scikit-HEP developers and users.

docs-sphinx/make_changelog.py

@@ -0,0 +1,135 @@
+# # BSD 3-Clause License; see https://github.com/jpivarski/awkward-1.0/blob/master/LICENSE
+
+# import math
+# import json
+# import subprocess
+# import re
+# import http.client
+# import datetime
+
+# tagslist_text = subprocess.run(["git", "show-ref", "--tags"], stdout=subprocess.PIPE).stdout
+# tagslist = dict(re.findall(rb"([0-9a-f]{40}) refs/tags/([0-9\.]+)", tagslist_text))
+
+# subjects_text = subprocess.run(["git", "log", "--format='format:%H %s'"], stdout=subprocess.PIPE).stdout
+# subjects = re.findall(rb"([0-9a-f]{40}) (.*)", subjects_text)
+
+# github_connection = http.client.HTTPSConnection("api.github.com")
+# github_releases = []
+# numpages = int(math.ceil(len(tagslist) / 30.0))
+# for pageid in range(numpages):
+#     print("Requesting GitHub data, page {0} of {1}".format(pageid + 1, numpages))
+#     github_connection.request("GET", r"/repos/scikit-hep/awkward-1.0/releases?page={0}&per_page=30".format(pageid + 1), headers={"User-Agent": "awkward1-changelog"})
+#     github_releases_text = github_connection.getresponse().read()
+#     try:
+#         github_releases_page = json.loads(github_releases_text)
+#     except:
+#         print(github_releases_text)
+#         raise
+#     print(len(github_releases_page))
+#     github_releases.extend(github_releases_page)
+
+# releases = {x["tag_name"]: x["body"] for x in github_releases if "tag_name" in x and "body" in x}
+# dates = {x["tag_name"]: datetime.datetime.fromisoformat(x["published_at"].rstrip("Z")).strftime("%A, %d %B, %Y") for x in github_releases if "tag_name" in x and "published_at" in x}
+# tarballs = {x["tag_name"]: x["tarball_url"] for x in github_releases if "tag_name" in x and "tarball_url" in x}
+# zipballs = {x["tag_name"]: x["zipball_url"] for x in github_releases if "tag_name" in x and "zipball_url" in x}
+
+# pypi_connection = http.client.HTTPSConnection("pypi.org")
+
+# def pypi_exists(tag):
+#     print("Looking for release {0} on PyPI...".format(tag))
+#     pypi_connection.request("HEAD", "/project/awkward1/{0}/".format(tag))
+#     response = pypi_connection.getresponse()
+#     response.read()
+#     return response.status == 200
+
+# with open("_auto/changelog.rst", "w") as outfile:
+#     outfile.write("Release history\n")
+#     outfile.write("---------------\n")
+
+#     first = True
+#     numprs = None
+
+#     for taghash, subject in subjects:
+#         if taghash in tagslist:
+#             tag = tagslist[taghash].decode()
+#             tagurl = "https://github.com/scikit-hep/awkward-1.0/releases/tag/{0}".format(tag)
+
+#             if numprs == 0:
+#                 outfile.write("*(no pull requests)*\n")
+#             numprs = 0
+
+#             header_text = "\nRelease `{0} <{1}>`__\n".format(tag, tagurl)
+#             outfile.write(header_text)
+#             outfile.write("="*len(header_text) + "\n\n")
+
+#             if tag in dates:
+#                 date_text = "**" + dates[tag] + "**"
+#             else:
+#                 date_text = ""
+
+#             assets = []
+#             if pypi_exists(tag):
+#                 assets.append("`pip <https://pypi.org/project/awkward1/{0}/>`__".format(tag))
+#             if tag in tarballs:
+#                 assets.append("`tar <{0}>`__".format(tarballs[tag]))
+#             if tag in zipballs:
+#                 assets.append("`zip <{0}>`__".format(zipballs[tag]))
+#             if len(assets) == 0:
+#                 assets_text = ""
+#             else:
+#                 assets_text = " ({0})".format(", ".join(assets))
+
+#             if len(date_text) + len(assets_text) > 0:
+#                 outfile.write("{0}{1}\n\n".format(date_text, assets_text))
+
+#             if tag in releases:
+#                 text = releases[tag].strip().replace("For details, see the [release history](https://awkward-array.readthedocs.io/en/latest/_auto/changelog.html).", "")
+#                 text = re.sub(r"([a-zA-Z0-9\-_]+/[a-zA-Z0-9\-_]+)#([1-9][0-9]*)", r"`\1#\2 <https://github.com/\1/issues/\2>`__", text)
+#                 text = re.sub(r"([^a-zA-Z0-9\-_])#([1-9][0-9]*)", r"\1`#\2 <https://github.com/scikit-hep/awkward-1.0/issues/\2>`__", text)
+#                 outfile.write(text + "\n\n")
+
+#             first = False
+
+#         m = re.match(rb"(.*) \(#([1-9][0-9]*)\)", subject)
+#         if m is not None:
+#             if numprs is None:
+#                 numprs = 0
+#             numprs += 1
+
+#             if first:
+#                 header_text = "\nUnreleased (`master branch <https://github.com/scikit-hep/awkward-1.0>`__ on GitHub)\n"
+#                 outfile.write(header_text)
+#                 outfile.write("="*len(header_text) + "\n\n")
+
+#             text = m.group(1).decode().strip()
+#             prnum = m.group(2).decode()
+#             prurl = "https://github.com/scikit-hep/awkward-1.0/pull/{0}".format(prnum)
+
+#             known = [prnum]
+#             for issue in re.findall(r"([a-zA-Z0-9\-_]+/[a-zA-Z0-9\-_]+)#([1-9][0-9]*)", text):
+#                 known.append(issue)
+#             for issue in re.findall(r"([^a-zA-Z0-9\-_])#([1-9][0-9]*)", text):
+#                 known.append(issue[1])
+
+#             text = re.sub(r"`", "``", text)
+#             text = re.sub(r"([a-zA-Z0-9\-_]+/[a-zA-Z0-9\-_]+)#([1-9][0-9]*)", r"`\1#\2 <https://github.com/\1/issues/\2>`__", text)
+#             text = re.sub(r"([^a-zA-Z0-9\-_])#([1-9][0-9]*)", r"\1`#\2 <https://github.com/scikit-hep/awkward-1.0/issues/\2>`__", text)
+#             if re.match(r".*[a-zA-Z0-9_]$", text):
+#                 text = text + "."
+
+#             body_text = subprocess.run(["git", "log", "-1", taghash.decode(), "--format='format:%b'"], stdout=subprocess.PIPE).stdout.decode()
+#             addresses = []
+#             for issue in re.findall(r"([a-zA-Z0-9\-_]+/[a-zA-Z0-9\-_]+)#([1-9][0-9]*)", body_text):
+#                 if issue not in known:
+#                     addresses.append("`{0}#{1} <https://github.com/{0}/issues/{1}>`__".format(issue[0], issue[1]))
+#             for issue in re.findall(r"([^a-zA-Z0-9\-_])#([1-9][0-9]*)", body_text):
+#                 if issue[1] not in known:
+#                     addresses.append("`#{0} <https://github.com/scikit-hep/awkward-1.0/issues/{0}>`__".format(issue[1]))
+#             if len(addresses) == 0:
+#                 addresses_text = ""
+#             else:
+#                 addresses_text = " (**also:** {0})".format(", ".join(addresses))
+
+#             outfile.write("* PR `#{0} <{1}>`__: {2}{3}\n".format(prnum, prurl, text, addresses_text))
+
+#             first = False