[DOCS] Fix example/ docs and add tests/ docs

Aedial · May 22, 2023 · 4d86a5f · 4d86a5f
1 parent 6e19a2d
commit 4d86a5f
Show file tree

Hide file tree

Showing 8 changed files with 54 additions and 14 deletions.
diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@ This module is intended to be used by developers as a helper for using NovelAI's
 | Pypi             | [![PyPI](https://img.shields.io/pypi/v/novelai-api)](https://pypi.org/project/novelai-api) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/novelai-api)](https://pypi.org/project/novelai-api) [![PyPI - License](https://img.shields.io/pypi/l/novelai-api)](https://pypi.org/project/novelai-api/) [![PyPI - Format](https://img.shields.io/pypi/format/novelai-api)](https://pypi.org/project/novelai-api/)                                                                                                                                                                                                                                                                                               |
 | Quality checking | [![Python package](https://github.com/Aedial/novelai-api/actions/workflows/python-package.yml/badge.svg)](https://github.com/Aedial/novelai-api/actions/workflows/python-package.yml) [![Python package](https://github.com/Aedial/novelai-api/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/Aedial/novelai-api/actions/workflows/codeql-analysis.yml) [![linting: pylint](https://img.shields.io/badge/linting-pylint-yellowgreen)](https://github.com/PyCQA/pylint) [![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) |
 | Stats            | [![GitHub top language](https://img.shields.io/github/languages/top/Aedial/novelai-api)](https://github.com/Aedial/novelai-api/search?l=python) ![Libraries.io dependency status for GitHub repo](https://img.shields.io/librariesio/github/Aedial/novelai-api) ![GitHub repo size](https://img.shields.io/github/repo-size/Aedial/novelai-api) ![Pypi package size](https://byob.yarr.is/Aedial/novelai-api/pypi-size) ![GitHub issues](https://img.shields.io/github/issues-raw/Aedial/novelai-api) ![GitHub pull requests](https://img.shields.io/github/issues-pr-raw/Aedial/novelai-api)                                                                                                                                 |
-| Activity         | ![GitHub last commit](https://img.shields.io/github/last-commit/Aedial/novelai-api) ![GitHub commits since tagged version](https://img.shields.io/github/commits-since/Aedial/novelai-api/0.12.2) ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/Aedial/novelai-api)                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Activity         | ![GitHub last commit](https://img.shields.io/github/last-commit/Aedial/novelai-api) ![GitHub commits since tagged version](https://img.shields.io/github/commits-since/Aedial/novelai-api/v0.12.2) ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/Aedial/novelai-api)                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
 
 # Usage
@@ -73,6 +73,7 @@ poetry run nai-pre-commit
 
 ## Testing against the API
 To run against the API, you can use `poetry run nai-test-api`.
+
 [API](tests/api)
 
 ## Testing against the mocked API

diff --git a/README_TEMPLATE.md b/README_TEMPLATE.md
@@ -10,7 +10,7 @@ This module is intended to be used by developers as a helper for using NovelAI's
 | Pypi             | [![PyPI](https://img.shields.io/pypi/v/novelai-api)](https://pypi.org/project/novelai-api) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/novelai-api)](https://pypi.org/project/novelai-api) [![PyPI - License](https://img.shields.io/pypi/l/novelai-api)](https://pypi.org/project/novelai-api/) [![PyPI - Format](https://img.shields.io/pypi/format/novelai-api)](https://pypi.org/project/novelai-api/)                                                                                                                                                                                                                                                                                               |
 | Quality checking | [![Python package](https://github.com/Aedial/novelai-api/actions/workflows/python-package.yml/badge.svg)](https://github.com/Aedial/novelai-api/actions/workflows/python-package.yml) [![Python package](https://github.com/Aedial/novelai-api/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/Aedial/novelai-api/actions/workflows/codeql-analysis.yml) [![linting: pylint](https://img.shields.io/badge/linting-pylint-yellowgreen)](https://github.com/PyCQA/pylint) [![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) |
 | Stats            | [![GitHub top language](https://img.shields.io/github/languages/top/Aedial/novelai-api)](https://github.com/Aedial/novelai-api/search?l=python) ![Libraries.io dependency status for GitHub repo](https://img.shields.io/librariesio/github/Aedial/novelai-api) ![GitHub repo size](https://img.shields.io/github/repo-size/Aedial/novelai-api) ![Pypi package size](https://byob.yarr.is/Aedial/novelai-api/pypi-size) ![GitHub issues](https://img.shields.io/github/issues-raw/Aedial/novelai-api) ![GitHub pull requests](https://img.shields.io/github/issues-pr-raw/Aedial/novelai-api)                                                                                                                                 |
-| Activity         | ![GitHub last commit](https://img.shields.io/github/last-commit/Aedial/novelai-api) ![GitHub commits since tagged version](https://img.shields.io/github/commits-since/Aedial/novelai-api/{bumped_version}) ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/Aedial/novelai-api)                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Activity         | ![GitHub last commit](https://img.shields.io/github/last-commit/Aedial/novelai-api) ![GitHub commits since tagged version](https://img.shields.io/github/commits-since/Aedial/novelai-api/v{bumped_version}) ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/Aedial/novelai-api)                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
 
 # Usage
@@ -73,6 +73,7 @@ poetry run nai-pre-commit
 
 ## Testing against the API
 To run against the API, you can use `poetry run nai-test-api`.
+
 [API](tests/api)
 
 ## Testing against the mocked API

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -11,6 +11,7 @@
 from types import FunctionType
 from typing import List, Union
 
+import tomlkit as toml
 from sphinx.application import Sphinx
 from sphinx.ext.autodoc import Options
 
@@ -20,7 +21,9 @@
 project = "NovelAI API"
 copyright = f"{datetime.datetime.now().year}, Aedial"  # noqa (built-in), pylint: disable=W0622
 author = "Aedial"
-release = "0.11.6"
+
+PYPROJECT_PATH = Path(__file__).parent.parent.parent / "pyproject.toml"
+release = str(toml.loads(PYPROJECT_PATH.read_text("utf-8"))["tool"]["poetry"]["version"])
 
 sys.path.insert(0, os.path.abspath("../.."))
 sys.path.insert(0, os.path.abspath(".."))

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -33,10 +33,19 @@ example
    example/example
 
 
-API
----
+Test API
+--------
 
 .. toctree::
    :maxdepth: 2
 
    tests/api/api
+
+
+Test Mocked API
+---------------
+
+.. toctree::
+   :maxdepth: 2
+
+   tests/mock/mock
diff --git a/docs/source/tests/api/api.rst b/docs/source/tests/api/api.rst
@@ -1,13 +1,8 @@
 API directory
 =============
 
-Requirements
-------------
-
-
-Usage
------
-
+.. include:: ../../../../tests/api/README.md
+   :parser: myst_parser.sphinx_
 
 Content
 -------

diff --git a/docs/source/tests/mock/mock.rst b/docs/source/tests/mock/mock.rst
@@ -0,0 +1,12 @@
+Mock directory
+==============
+
+
+
+Content
+-------
+
+
+
+Reference
+---------
diff --git a/example/README.md b/example/README.md
@@ -1,5 +1,6 @@
 ### Requirements
 Requires the "NAI_USERNAME" and "NAI_PASSWORD" values provided via environment variables.
+They can be provided through a .env file at the root of the project.
 
 The "NAI_PROXY" environment variable is also supported to inject a proxy address.
 
@@ -13,6 +14,6 @@ python example/<filename>
 
 If you don't have the novelai-api package installed, or you're actively developing on the project :
 ```
-nox -s run -- example/<filename>
+poetry run python example/<filename>
 ```
-This option supports providing environment variables through a .env file
+Remember to run `poetry install` before running the example, if not already done.
diff --git a/tests/api/README.md b/tests/api/README.md
@@ -0,0 +1,18 @@
+### Requirements
+Requires the "NAI_USERNAME" and "NAI_PASSWORD" values provided via environment variables.
+They can be provided through a .env file at the root of the project.
+
+The "NAI_PROXY" environment variable is also supported to inject a proxy address.
+
+### Usage
+For running all the tests under the tests/api folder :
+```
+poetry run nai-test-api
+```
+
+For running a specific test files (using the [pytest name scheme](https://docs.pytest.org/en/7.3.x/how-to/usage.html#nodeids)) :
+```
+poetry run nai-test-api <filename 1> ... <filename n>
+```
+
+Remember to run `poetry install` before running the test, if not already done.