[DOCS][TEST] Expand docs to tests and fix some tests

README.md

@@ -19,14 +19,14 @@ Download via [pip](https://pypi.org/project/novelai-api):
 pip install novelai-api
 ```
 
-A full list of examples is available in the [example](/example) directory
+A full list of examples is available in the [example](example) directory
 
 The API works through the NovelAIAPI object.
 It is split in 2 groups: NovelAIAPI.low_level and NovelAIAPI.high_level
 
 ## low_level
 The low level interface is a strict implementation of the official API (<https://api.novelai.net/docs>).
-It only checks for input types via assert and output schema if NovelAIAPI.low_level.is_schema_validation_enabled is True
+It only checks for input types via assert, and output schema if NovelAIAPI.low_level.is_schema_validation_enabled is True
 
 ## high_level
 The high level interface builds on the low level one for easier handling of complex settings.

docs/source/conf.py

@@ -8,8 +8,8 @@
 import os
 import sys
 from pathlib import Path
-from types import ModuleType
-from typing import List
+from types import FunctionType
+from typing import List, Union
 
 from sphinx.application import Sphinx
 from sphinx.ext.autodoc import Options
@@ -32,6 +32,7 @@
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.extlinks",
     "sphinx.ext.viewcode",
     "myst_parser",
@@ -40,6 +41,8 @@
     "hoverxref.extension",
 ]
 
+add_module_names = False
+
 autodoc_class_signature = "separated"
 autodoc_member_order = "bysource"
 autodoc_typehints_format = "fully-qualified"
@@ -81,7 +84,11 @@
 # -- Hooks -------------------------------------------------------------------
 
 
-def format_docstring(_app: Sphinx, what: str, name: str, obj: ModuleType, _options: Options, lines: List[str]):
+def format_docstring(_app: Sphinx, what: str, name: str, obj, _options: Options, lines: List[str]):
+    """
+    Inject metadata in docstrings if necessary
+    """
+
     kwargs = {
         "obj_type": what,
         "obj_name": name,
@@ -99,5 +106,25 @@ def format_docstring(_app: Sphinx, what: str, name: str, obj: ModuleType, _optio
             lines[i] = line.format(**kwargs)
 
 
+def hide_test_signature(
+    _app: Sphinx,
+    what: str,
+    name: str,
+    _obj: FunctionType,
+    _options: Options,
+    signature: str,
+    return_annotation: Union[str, None],
+):
+    if what == "function":
+        module_name, *_, file_name, _func_name = name.split(".")
+
+        # erase signature for functions from test files
+        if module_name == "tests" and file_name.startswith("test_"):
+            return "", None
+
+    return signature, return_annotation
+
+
 def setup(app):
     app.connect("autodoc-process-docstring", format_docstring)
+    app.connect("autodoc-process-signature", hide_test_signature)

docs/source/index.rst

@@ -31,3 +31,12 @@ example
    :maxdepth: 2
 
    example/example
+
+
+API
+---
+
+.. toctree::
+   :maxdepth: 3
+
+   tests/api/api

docs/source/tests/api/api.boilerplate.rst

@@ -0,0 +1,7 @@
+boilerplate
+===========
+
+.. automodule:: tests.api.boilerplate
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/tests/api/api.rst

@@ -0,0 +1,47 @@
+API directory
+=============
+
+Requirements
+------------
+
+
+Usage
+-----
+
+
+Content
+-------
+
+test_decrypt_encrypt_integrity_check.py
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: tests.api.test_decrypt_encrypt_integrity_check
+   :members:
+
+test_imagegen_samplers.py
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: tests.api.test_imagegen_samplers
+   :members:
+
+test_sync_gen.py
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: tests.api.test_sync_gen
+   :members:
+
+test_textgen_presets.py
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: tests.api.test_textgen_presets
+   :members:
+
+test_textgen_sanity.py
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: tests.api.test_textgen_sanity
+   :members:
+
+
+Reference
+---------
+
+.. toctree::
+   :maxdepth: 2
+
+   api.boilerplate

novelai_api/__init__.py

@@ -1,2 +1,8 @@
+"""
+:class:`NovelAI_API`
+
+:class:`NovelAIError`
+"""
+
 from novelai_api.NovelAI_API import NovelAIAPI
 from novelai_api.NovelAIError import NovelAIError

noxfile.py

@@ -27,7 +27,7 @@ def get_dotenv(session: nox.Session):
     return json.loads(dotenv_str)
 
 
-def install_package(session: nox.Session, *packages: str, dev: bool = False):
+def install_package(session: nox.Session, *packages: str, dev: bool = False, docs: bool = False):
     session.install("poetry")
     session.install("python-dotenv")
 
@@ -40,6 +40,8 @@ def install_package(session: nox.Session, *packages: str, dev: bool = False):
     poetry_groups = []
     if dev:
         poetry_groups.extend(["--with", "dev"])
+    if docs:
+        poetry_groups.extend(["--with", "docs"])
 
     session.run("python", "-m", "poetry", "export", "--output=requirements.txt", "--without-hashes", *poetry_groups)
     session.run("python", "-m", "poetry", "build", "--format=wheel")
@@ -99,8 +101,7 @@ def run(session: nox.Session):
 def build_docs(session: nox.Session):
     docs_path = pathlib.Path(__file__).parent / "docs"
 
-    install_package(session)
-    session.install("-r", str(docs_path / "requirements.txt"))
+    install_package(session, dev=True, docs=True)
 
     with session.chdir(docs_path):
         session.run("make", "html", external=True)

pyproject.toml

@@ -14,6 +14,9 @@ classifiers = [
 ]
 packages = [{include = "novelai_api"}]
 
+[tool.poetry.urls]
+"Bug Tracker" = "https://github.com/Aedial/novelai-api/issues"
+
 [tool.poetry.dependencies]
 python = ">=3.7.2,<3.12"
 aiohttp = {extras = ["speedups"], version = "^3.8.3"}
@@ -31,6 +34,15 @@ pytest-asyncio = "^0.20.1"
 pytest-randomly = "^3.12.0"
 pylint = "^2.15.5"
 
+[tool.poetry.group.docs.dependencies]
+sphinx = "^5.3.0"
+# patched repo to work with relative links
+myst_parser = {git = "https://github.com/Aedial/MyST-Parser", rev = "adcdb9a"}
+linkify-it-py = "^2.0.0"
+sphinx-copybutton = "^0.5.2"
+sphinx-last-updated-by-git = "^0.3.4"
+sphinx-hoverxref = "^1.3.0"
+
 [tool.flake8]
 # TODO: add flake when supports come (https://github.com/PyCQA/flake8/issues/234)
 

tests/api/boilerplate.py

@@ -124,6 +124,10 @@ async def wrap(*args, **kwargs):
 
 
 class JSONEncoder(json.JSONEncoder):
+    """
+    Extended JSON encoder to support bytes
+    """
+
     def default(self, o: Any) -> Any:
         if isinstance(o, bytes):
             return o.hex()
@@ -132,6 +136,10 @@ def default(self, o: Any) -> Any:
 
 
 def dumps(e: Any) -> str:
+    """
+    Shortcut to a configuration of json.dumps for consistency
+    """
+
     return json.dumps(e, indent=4, ensure_ascii=False, cls=JSONEncoder)
 
 

tests/api/conftest.py

@@ -13,15 +13,13 @@ def pytest_terminal_summary(terminalreporter):
         terminalreporter.write_sep("=", "XFAIL summary info", cyan=True, bold=True)
 
     for rep in xfailed:
-        reason = getattr(rep, "wasxfail", "")
-        terminalreporter.write("XFAIL", yellow=True)
-        terminalreporter.write(f" {rep.nodeid} - {reason}\n")
+        if not rep.failed:
+            reason = getattr(rep, "wasxfail", "")
+            terminalreporter.write("XFAIL", yellow=True)
+            terminalreporter.write(f" {rep.nodeid} - {reason}\n")
 
-        rep.longrepr.toterminal(terminalreporter._tw)
-        terminalreporter.line("")
-
-
-# TODO: add html reporting
+            rep.longrepr.toterminal(terminalreporter._tw)
+            terminalreporter.line("")
 
 
 # cannot put in boilerplate because pytest is a mess
@@ -31,7 +29,7 @@ def event_loop():
     yield loop
 
     # clean any remaining task to avoid the warning about pending tasks
-    tasks = asyncio.Task.all_tasks(loop) if hasattr(asyncio.Task, "all_tasks") else asyncio.all_tasks(loop)
+    tasks = asyncio.all_tasks(loop)
     for task in tasks:
         # print(f"Cancelling task {task}")
         task.cancel()