[MISC] Add docs to Github Pages

.github/workflows/sphinx.yml

@@ -0,0 +1,32 @@
+name: Sphinx build
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.10"
+        cache: 'pip'
+
+    - name: Build HTML
+      uses: ammaraskar/sphinx-action@master
+      with:
+        docs-folder: "docs/"
+        pre-build-command: pip install nox
+        build-command: nox -s build-docs -- novelai_api
+
+    - name: Deploy on Github Pages
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/main'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html
+
+    # Add a deploy on RTD ?

TODO.md

@@ -1,7 +1,12 @@
 ### FIXME:
+    - Controlnet mask
+
+### Reviewing/Fixing:
+    - Backend mocking
 
 ### Work in Progress:
+    - https://pre-commit.ci/
+
     - Story handling
     - Context building
     - Contribute to flake2pylint
-    - Backend mocking

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -W --keep-going
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# 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/requirements.txt

@@ -0,0 +1,5 @@
+sphinx==6.1.3
+myst-parser
+sphinx-copybutton
+sphinx_last_updated_by_git
+sphinx-hoverxref

docs/source/conf.py

@@ -0,0 +1,64 @@
+# 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
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "NovelAI API"
+# pylint: disable=W0622
+copyright = "2023, Aedial"  # noqa (built-in)
+author = "Aedial"
+release = "0.11.6"
+
+sys.path.insert(0, os.path.abspath("../.."))
+sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath("."))
+
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.viewcode",
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinx_last_updated_by_git",
+    "hoverxref.extension",
+]
+
+autodoc_member_order = "bysource"
+
+extlinks = {"issue": ("https://github.com/sphinx-doc/sphinx/issues/%s", "[issue %s]")}
+
+suppress_warnings = ["myst.header"]
+
+copybutton_exclude = ".linenos, .gp, .go"
+
+hoverxref_auto_ref = True
+hoverxref_domains = ["py"]
+hoverxref_role_types = {
+    "hoverxref": "modal",
+    "ref": "modal",  # for hoverxref_auto_ref config
+    "confval": "modal",  # for custom object
+    "mod": "modal",  # for Python Sphinx Domain
+    "class": "modal",  # for Python Sphinx Domain
+}
+
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "classic"
+# no asset yet
+# html_static_path = ['_static']

docs/source/index.rst

@@ -0,0 +1,20 @@
+.. NovelAI API documentation master file, created by
+   sphinx-quickstart on Wed Apr 19 16:51:01 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
+
+TODO
+====
+.. include:: ../../TODO.md
+   :parser: myst_parser.sphinx_
+
+Reference
+=========
+.. toctree::
+   :maxdepth: 2
+
+   novelai_api

docs/source/novelai_api.BanList.rst

@@ -0,0 +1,7 @@
+novelai\_api.BanList module
+===========================
+
+.. automodule:: novelai_api.BanList
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/novelai_api.BiasGroup.rst

@@ -0,0 +1,7 @@
+novelai\_api.BiasGroup module
+=============================
+
+.. automodule:: novelai_api.BiasGroup
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/novelai_api.GlobalSettings.rst

@@ -0,0 +1,7 @@
+novelai\_api.GlobalSettings module
+==================================
+
+.. automodule:: novelai_api.GlobalSettings
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/novelai_api.Idstore.rst

@@ -0,0 +1,7 @@
+novelai\_api.Idstore module
+===========================
+
+.. automodule:: novelai_api.Idstore
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/novelai_api.ImagePreset.rst

@@ -0,0 +1,7 @@
+novelai\_api.ImagePreset module
+===============================
+
+.. automodule:: novelai_api.ImagePreset
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/novelai_api.Keystore.rst

@@ -0,0 +1,7 @@
+novelai\_api.Keystore module
+============================
+
+.. automodule:: novelai_api.Keystore
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/novelai_api.NovelAIError.rst

@@ -0,0 +1,7 @@
+novelai\_api.NovelAIError module
+================================
+
+.. automodule:: novelai_api.NovelAIError
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/novelai_api.NovelAI_API.rst

@@ -0,0 +1,7 @@
+novelai\_api.NovelAI\_API module
+================================
+
+.. automodule:: novelai_api.NovelAI_API
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/novelai_api.Preset.rst

@@ -0,0 +1,7 @@
+novelai\_api.Preset module
+==========================
+
+.. automodule:: novelai_api.Preset
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/novelai_api.SchemaValidator.rst

@@ -0,0 +1,7 @@
+novelai\_api.SchemaValidator module
+===================================
+
+.. automodule:: novelai_api.SchemaValidator
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/novelai_api.StoryHandler.rst

@@ -0,0 +1,7 @@
+novelai\_api.StoryHandler module
+================================
+
+.. automodule:: novelai_api.StoryHandler
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/novelai_api.Tokenizer.rst

@@ -0,0 +1,7 @@
+novelai\_api.Tokenizer module
+=============================
+
+.. automodule:: novelai_api.Tokenizer
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/novelai_api.python_utils.rst

@@ -0,0 +1,7 @@
+novelai\_api.python\_utils module
+=================================
+
+.. automodule:: novelai_api.python_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/novelai_api.rst

@@ -0,0 +1,20 @@
+novelai\_api package
+====================
+
+.. toctree::
+   :maxdepth: 2
+
+   novelai_api.BanList
+   novelai_api.BiasGroup
+   novelai_api.GlobalSettings
+   novelai_api.Idstore
+   novelai_api.ImagePreset
+   novelai_api.Keystore
+   novelai_api.NovelAIError
+   novelai_api.NovelAI_API
+   novelai_api.Preset
+   novelai_api.SchemaValidator
+   novelai_api.StoryHandler
+   novelai_api.Tokenizer
+   novelai_api.utils
+   novelai_api.python_utils

docs/source/novelai_api.utils.rst

@@ -0,0 +1,7 @@
+novelai\_api.utils module
+=========================
+
+.. automodule:: novelai_api.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

novelai_api/GlobalSettings.py

@@ -2,6 +2,7 @@
 
 from novelai_api.BiasGroup import BiasGroup
 from novelai_api.Preset import Model
+from novelai_api.python_utils import expand_kwargs
 from novelai_api.Tokenizer import Tokenizer
 
 
@@ -597,21 +598,22 @@ class GlobalSettings:
 
     # type completion for __setitem__ and __getitem__
     if TYPE_CHECKING:
-        # generate up to 20 tokens after max_length if an end of sentence if found within these 20 tokens
+        #: Generate up to 20 tokens after max_length if an end of sentence if found within these 20 tokens
         generate_until_sentence: bool
-        # number of logprobs to return for each token. Set to NO_LOGPROBS to disable
+        #: Number of logprobs to return for each token. Set to NO_LOGPROBS to disable
         num_logprobs: int
-        # apply the BRACKET biases
+        #: Apply the BRACKET biases
         ban_brackets: bool
-        # apply the DINKUS_ASTERISM biases
+        #: Apply the DINKUS_ASTERISM biases
         bias_dinkus_asterism: bool
-        # apply the GENJI_AMBIGUOUS_TOKENS if model is Genji
+        #: Apply the GENJI_AMBIGUOUS_TOKENS if model is Genji
         ban_ambiguous_genji_tokens: bool
 
     NO_LOGPROBS = -1
 
     _settings: Dict[str, Any]
 
+    @expand_kwargs(_DEFAULT_SETTINGS.keys(), (type(e) for e in _DEFAULT_SETTINGS.values()))
     def __init__(self, **kwargs):
         object.__setattr__(self, "_settings", {})