[WIP, DO NOT MERGE] documenting

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    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+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/README.md

@@ -0,0 +1,10 @@
+# Luogu-api-python/docs
+
+Luogu-api-python uses sphinx to generate documents for this library.
+
+## TODO
+
+- [ ] Examples
+- [ ] Quickstart
+- [ ] Contributing
+- [ ] Autodocs

docs/conf.py

@@ -0,0 +1,27 @@
+# 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
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'luogu-api-python'
+copyright = '2025, bzy-nya<[email protected]>, Camber Huang<[email protected]>'
+author = 'bzy-nya<[email protected]>, Camber Huang<[email protected]>'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,23 @@
+.. luogu-api-python documentation master file, created by
+   sphinx-quickstart on Sun Feb 16 09:19:49 2025.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+luogu-api-python documentation
+==============================
+
+``luogu-api-python`` is a community-driven Python implementation of the Luogu API. It provides an interface to interact with the Luogu online judge system, allowing users to programmatically manage problems and user operations on Luogu. This library aims to simplify automating tasks on Luogu with easy-to-use methods and classes.
+
+Contents
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   quickstart
+   examples
+   about
+
+
+
+

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/quickstart.rst

@@ -0,0 +1,53 @@
+Quickstart
+==========
+
+Installation
+------------
+
+To install ``luogu-api-python``, simply run this command in your terminal of choice::
+
+    $ pip3 install luogu-api-python
+
+Installing via source is also available, for example, clone the repository::
+
+    $ git clone https://github.com/NekoOS-Group/luogu-api-python.git 
+
+and install::
+
+    $ cd luogu-api-python
+    $ python3 -m pip install .
+
+Synchronous API
+---------------
+
+Here is an example of how to use::
+
+    import pyLuogu
+
+    # Initialize the API without cookies
+    luogu = pyLuogu.luoguAPI()
+
+    # Get a list of problems
+    problems = luogu.get_problem_list().problems
+    for problem in problems:
+        print(problem.title)
+
+Asynchronous API (Experimental)
+-------------------------------
+
+``luogu-api-python`` also provides experimental support for async operations::
+
+    import asyncio
+    import pyLuogu
+
+    # Initialize the async API without cookies
+    luogu = pyLuogu.asyncLuoguAPI()
+
+    async def main():
+        problems = (await luogu.get_problem_list()).problems
+        for problem in problems:
+            print(problem.title)
+
+    asyncio.run(main())
+
+

pyLuogu/api.py

@@ -10,7 +10,16 @@
 from .errors import *
 from . import logger
 
+__COMMON_UA = "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:133.0) Gecko/20100101 Firefox/133."
+
 class luoguAPI:
+    """ Luogu API interface interacting via Requests
+
+    Attributes:
+        base_url (str): The base URL for the Luogu API. Defaults to "https://www.luogu.com.cn".
+        cookies (LuoguCookies or None)
+
+    """
     def __init__(
             self,
             base_url="https://www.luogu.com.cn",
@@ -558,4 +567,4 @@ def get_tags(self) -> TagRequestResponse:
 
     def get_image(self, id: int) -> Image:
         res = self._send_request(endpoint=f"/api/image/detail/{id}")
-        return Image(res["image"])
+        return Image(res["image"])

pyLuogu/async_api.py

@@ -11,6 +11,8 @@
 from . import logger
 
 class asyncLuoguAPI:
+    """ 
+    """
     def __init__(
             self,
             base_url="https://www.luogu.com.cn",
@@ -481,4 +483,4 @@ async def get_record(self, rid: str) -> RecordRequestResponse:
 
     async def get_tags(self) -> TagRequestResponse:
         res = await self._send_request(endpoint="/_lfe/tags")
-        return TagRequestResponse(res)
+        return TagRequestResponse(res)

pyLuogu/types.py

@@ -95,6 +95,8 @@
 TransferProblemType = Literal["P", "U", "B"] | int
 
 class LuoguType(JsonSerializable, Printable):
+    """Inherit from 
+    """
     __type_dict__ = {}
 
     def __init__(self,json=None):
@@ -119,15 +121,27 @@ class PagedList(LuoguType, Generic[T_of_list]):
     perPage: int
 
 class ListRequestParams(RequestParams):
+    """Common Parameters for Requests about list """
     __type_dict__ = {
         "page": int,
         "orderBy": int
     }
 
 class ProblemListRequestParams(ListRequestParams):
+    """Parameters for requesting a list of problems. Use for GET /problem/list;
+
+    Attributes:
+        page (int): The page number to retrieve.
+        orderBy (int): The order in which to sort the problems.
+        keyword (str): A keyword to filter the problems.
+        content (bool): When 
+        type (ProblemType): The type of problem.
+        difficulty (int): The difficulty level of the problems.
+        tag (str): A tag to filter the problems.
+    """
     __type_dict__ = {
         "page": int,
-        "orderBy": int,
+        "orderBy": Literal["","name","pid","difficulty"],
         "keyword": str,
         "content": bool,
         "type": str,