From a3258c2ff5a1354178bae619afd0d5b1992f39db Mon Sep 17 00:00:00 2001 From: Battlefield Duck Date: Fri, 26 Jan 2024 19:49:33 +0800 Subject: [PATCH] Update docs --- .github/workflows/sphinx-gh-pages.yml | 6 ++--- docs/.gitignore | 2 -- docs/api/.gitignore | 1 + docs/index.rst | 19 ++++++++++++--- docs/install.rst | 14 +++++++++++ docs/usage.rst | 35 +++++++++++++++++++++++++++ opengsq/__init__.py | 2 +- tests/protocols/result_handler.py | 7 ------ 8 files changed, 70 insertions(+), 16 deletions(-) delete mode 100644 docs/.gitignore create mode 100644 docs/api/.gitignore create mode 100644 docs/install.rst create mode 100644 docs/usage.rst diff --git a/.github/workflows/sphinx-gh-pages.yml b/.github/workflows/sphinx-gh-pages.yml index a0d09c2..a2ed39d 100644 --- a/.github/workflows/sphinx-gh-pages.yml +++ b/.github/workflows/sphinx-gh-pages.yml @@ -36,7 +36,7 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 - + - name: Setup Pages uses: actions/configure-pages@v4 @@ -53,7 +53,7 @@ jobs: python -m pip install -r docs/requirements.txt - name: Sphinx API Documentation Generation - run: sphinx-apidoc -o docs opengsq + run: sphinx-apidoc -o docs opengsq/api - name: Sphinx HTML Documentation Build run: sphinx-build -b html docs docs/_build @@ -63,7 +63,7 @@ jobs: with: # Upload entire repository path: "docs/_build" - + - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 diff --git a/docs/.gitignore b/docs/.gitignore deleted file mode 100644 index 049a3c6..0000000 --- a/docs/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -*.rst -!index.rst diff --git a/docs/api/.gitignore b/docs/api/.gitignore new file mode 100644 index 0000000..30d8556 --- /dev/null +++ b/docs/api/.gitignore @@ -0,0 +1 @@ +*.rst diff --git a/docs/index.rst b/docs/index.rst index 39203ed..cab717b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,10 +7,23 @@ Welcome to OpenGSQ Python's documentation! ========================================== .. toctree:: - :maxdepth: 2 - :caption: Contents: + :maxdepth: 4 + :caption: Get Started + + Home + install + usage + +.. toctree:: + :maxdepth: 4 + :caption: API + + api/modules + +.. toctree:: + :maxdepth: 4 + :caption: Tests - modules Indices and tables ================== diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..dd9af02 --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,14 @@ +Installation +============ + +You can install the OpenGSQ library using pip: + +.. code-block:: console + + (.venv) $ pip install --upgrade opengsq + +Alternatively, you can install from source manually: + +.. code-block:: console + + (.venv) $ python setup.py install diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..fa942a0 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,35 @@ +Usage +===== + +Here's an example of how to query a server using the Source protocol: + +.. code-block:: python + + import asyncio + from opengsq.protocols import Source + + async def main(): + source = Source(host='45.147.5.5', port=27015) + info = await source.get_info() + print(info) + + asyncio.run(main()) + +You can also use the Source Remote Console: + +.. code-block:: python + + import asyncio + from opengsq.exceptions import AuthenticationException + from opengsq.protocols import Source + + async def main(): + with Source.RemoteConsole('123.123.123.123', 27015) as rcon: + try: + await rcon.authenticate('serverRconPassword') + result = await rcon.send_command('cvarlist') + print(result) + except AuthenticationException: + print('Failed to authenticate') + + asyncio.run(main()) diff --git a/opengsq/__init__.py b/opengsq/__init__.py index 4fd04c0..7f1ff57 100644 --- a/opengsq/__init__.py +++ b/opengsq/__init__.py @@ -3,7 +3,7 @@ """ OpenGSQ Python Library -~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~ Python library for querying game servers diff --git a/tests/protocols/result_handler.py b/tests/protocols/result_handler.py index e6b9628..0376dfd 100644 --- a/tests/protocols/result_handler.py +++ b/tests/protocols/result_handler.py @@ -1,5 +1,4 @@ import asyncio -from dataclasses import asdict, is_dataclass import json import os from pathlib import Path @@ -20,12 +19,6 @@ async def save_result(self, function_name, result, is_json=True): if self.enable_save: if is_json: - # if is_dataclass(result): - # result = asdict(result) - # elif isinstance(result, list): - # # set asdict to all items - # result = [asdict(item) for item in result if is_dataclass(item)] - result = json.dumps(result, indent=4, ensure_ascii=False, default=lambda o: o.__dict__) with open(os.path.join(self.__protocol_path, f'{function_name}.{(is_json and "json" or "txt")}'), 'w', encoding='utf-8') as f: