make api_utils.py private and write docs

Author: skysomorphic

docs/api/qbreader.api_utils.rst

@@ -7,7 +7,6 @@ Submodules
 .. toctree::
    :maxdepth: 4
 
-   qbreader.api_utils
    qbreader.asynchronous
    qbreader.synchronous
    qbreader.types

docs/api/qbreader.rst

@@ -32,6 +32,22 @@
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 default_role = "py:obj"
 
+highlight_language = "python3"
+
+autodoc_member_order = "bysource"
+autodoc_type_aliases = {
+    "Async": "qbreader.asynchronous.Async",
+    "Sync": "qbreader.synchronous.Sync",
+    "Tossup": "qbreader.types.Tossup",
+    "Bonus": "qbreader.types.Bonus",
+    "Category": "qbreader.types.Category",
+    "Subcategory": "qbreader.types.Subcategory",
+    "Difficulty": "qbreader.types.Difficulty",
+    "QueryResponse": "qbreader.types.QueryResponse",
+    "Directive": "qbreader.types.Directive",
+    "AnswerJudgement": "qbreader.types.AnswerJudgement",
+    "Packet": "qbreader.types.Packet",
+}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/conf.py

@@ -3,18 +3,45 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to python-qbreader's documentation!
-===========================================
+python-qbreader
+===============
 
 .. toctree::
    :hidden:
    :caption: API Reference
 
    qbreader <api/qbreader>
 
-Indices and tables
-==================
+.. toctree::
+   :hidden:
+   :caption: Indices
+
+   genindex
+   modindex
+
+``qbreader`` is a Python wrapper to the qbreader_ API as well as a general quizbowl library. It provides
+both asynchronous and synchronous interfaces to the API along with functionality for representing questions.
+
+A small example
+---------------
+
+.. code:: python
+
+   >>> from qbreader import Sync as qbr # synchronous interface
+   >>> tossup = qbr.random_tossup()[0]
+   >>> tossup.question
+   'Tim Peters wrote 19 “guiding principles” of this programming language, which include the maxim “Complex is better than complicated.” The “pandas” library was written for this language. Unicode string values had to be defined with a “u” in version 2 of this language. Libraries in this language include Tkinter, Tensorflow, (*) NumPy (“numb pie”) and SciPy (“sigh pie”). The framework Django was written in this language. This language uses “duck typing.” Variables in this language are often named “spam” and “eggs.” Guido van Rossum invented, for 10 points, what programming language named for a British comedy troupe?'
+   >>> tossup.answer
+   'Python'
+   >>> tossup.category
+   <Category.SCIENCE: 'Science'>
+   >>> tossup.subcategory
+   <Subcategory.OTHER_SCIENCE: 'Other Science'>
+   >>> tossup.difficulty
+   <Difficulty.HS_HARD: '4'>
+   >>> tossup.set
+   '2022 Prison Bowl'
+   >>> (tossup.packet_number, tossup.question_number)
+   (4, 20)
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. _qbreader: https://www.qbreader.org/

docs/index.rst

@@ -2,8 +2,8 @@
 
 import importlib.metadata
 
-import qbreader.synchronous as Sync
 from qbreader.asynchronous import Async
+from qbreader.synchronous import Sync
 from qbreader.types import (
     AnswerJudgement,
     Bonus,

qbreader/__init__.py

@@ -4,7 +4,7 @@
 
 import aiohttp
 
-import qbreader.api_utils as api_utils
+import qbreader._api_utils as api_utils
 from qbreader._consts import BASE_URL
 from qbreader.types import (
     AnswerJudgement,