Merge pull request #30 from gunyu1019/docs

[Docs] Add document about chzzkpy
gunyu1019 · Nov 15, 2024 · 7aeadef · 7aeadef
2 parents ab2dcb5 + 2262a42
commit 7aeadef
Show file tree

Hide file tree

Showing 17 changed files with 1,724 additions and 1 deletion.
diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml
@@ -0,0 +1,66 @@
+on:
+  push:
+    branches: 
+      - 'docs'
+
+name: Document (Build & Deployment)
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      python-verison: '3.11'
+    strategy: 
+      matrix:
+        language: [ 'en', 'ko' ]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: '${{ env.python-verison }}'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[docs]
+      - name: Build
+        run: sphinx-build './docs/source' './docs/build/${{ matrix.language }}' -D language='${{ matrix.language }}' 
+      - name: Store artifact (language = ${{ matrix.language }})
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-${{ matrix.language }}
+          path: ./docs/build/${{ matrix.language }}
+  integrate:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Download artifact (language = ko)
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-ko
+          path: ./docs/build/ko
+      - name: Download artifact (language = en)
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-en
+          path: ./docs/build/en
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Upload integrated artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/build/
+  deploy:
+    environment:
+      name: github-pages
+      url: '${{ steps.deployment.outputs.page_url }}/ko'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    needs: integrate
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/chzzkpy/chat/__init__.py b/chzzkpy/chat/__init__.py
@@ -25,13 +25,17 @@
 from .chat_client import ChatClient
 from .connected import ConnectedInfo
 from .donation import (
+    DonationRank,
+    BaseDonation,
     ChatDonation,
     VideoDonation,
     MissionDonation,
 )
 from .enums import ChatType, ChatCmd, UserRole
 from .error import *
 from .message import (
+    Message,
+    MessageDetail,
     ChatMessage,
     NoticeMessage,
     DonationMessage,
@@ -41,6 +45,8 @@
     ChatDonationExtra,
     VideoDonationExtra,
     MissionDonationExtra,
+    SubscriptionExtra,
+    SystemExtraParameter,
     NoticeExtra,
     SystemExtra,
 )

diff --git a/chzzkpy/error.py b/chzzkpy/error.py
@@ -30,20 +30,23 @@ class ChzzkpyException(Exception):
 
 
 class LoginRequired(ChzzkpyException):
+    """Exception that’s raised when a method need login."""
     def __init__(self):
         super(LoginRequired, self).__init__(
             "This method(feature) needs to login. Please use `login()` method."
         )
 
 
 class NotFound(ChzzkpyException):
+    """Exception that’s raised for when status code 404 occurs."""
     def __init__(self, message: Optional[str] = None):
         if message is None:
             message = "Not Found"
         super(NotFound, self).__init__(message)
 
 
 class HTTPException(ChzzkpyException):
+    """Exception that’s raised when an HTTP request operation fails."""
     def __init__(self, code: int, message: Optional[str] = None):
         if message is None:
             message = f"Reponsed error code ({code})"

diff --git a/docs/Makefile b/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     = 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)
diff --git a/docs/make.bat b/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=source
+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
diff --git a/docs/source/_static/custom_theme.css b/docs/source/_static/custom_theme.css
@@ -0,0 +1,27 @@
+#content ul:not(.search) p, #content ul:not(.search)>li {
+    margin-top: 0 !important;
+}
+
+.sig {
+    border-top-width: 0 !important;
+    padding: 0 !important;
+}
+
+.py.class > .sig.sig-object, 
+.py.method > .sig.sig-object,
+.py.function > .sig.sig-object, 
+.py.property > .sig.sig-object,
+.py.exception > .sig.sig-object {
+    padding: .2rem .5rem !important;
+    background: hsl(var(--border));
+    border-radius: .5rem;
+}
+
+
+.py.class > .sig.sig-object .property .pre, 
+.py.method > .sig.sig-object .property .pre,
+.py.function > .sig.sig-object .property .pre, 
+.py.property > .sig.sig-object .property .pre,
+.py.exception > .sig.sig-object .property .pre {
+    color: #f0a63c !important;
+}
diff --git a/docs/source/_templates/global_sidebar_toc.html b/docs/source/_templates/global_sidebar_toc.html
@@ -0,0 +1,3 @@
+<nav class="table w-full min-w-full my-6 lg:my-8">
+    {{ toctree(collapse=False, includehidden=true) }}
+</nav>
diff --git a/docs/source/_templates/header.html b/docs/source/_templates/header.html
@@ -0,0 +1,129 @@
+{#- Template file for the header -#}
+
+<header
+  class="sticky top-0 z-40 w-full border-b shadow-sm border-border supports-backdrop-blur:bg-background/60 bg-background/95 backdrop-blur">
+
+  {#- Extra block at the top of the header #}
+  {%- block header_before %}{% endblock header_before -%}
+
+  <div class="container flex items-center h-14">
+    {#- show logo and extra header links on the left side of the header -#}
+    {%- block header_left %}
+    <div class="hidden mr-4 md:flex">
+      {%- block header_logo %}
+      <a href="{{ pathto(master_doc) }}" class="flex items-center mr-6">
+        {%- if logo_url %}
+          <img height="24" width="24" class="mr-2 dark:invert" src="{{ logo_url }}" alt="Logo" />
+        {%- endif -%}
+        {%- if theme_logo_dark and not logo_url %}
+          <img width="24" height="24" class="mr-2 hidden dark:block" src="{{ pathto('_static/' + theme_logo_dark, 1) }}" alt="Logo" />
+        {%- endif -%}
+        {%- if theme_logo_light and not logo_url %}
+        <img width="24" height="24" class="mr-2 dark:hidden" src="{{ pathto('_static/' + theme_logo_light, 1) }}" alt="Logo" />
+        {%- endif -%}
+        <span class="hidden font-bold sm:inline-block text-clip whitespace-nowrap">{{ docstitle }}</span>
+      </a>
+      {%- endblock header_logo %}
+
+      {%- block header_main_nav %}
+      {%- if theme_main_nav_links|tobool -%}
+      <nav class="flex items-center space-x-6 text-sm font-medium">
+        {%- for text,url in theme_main_nav_links.items() %}
+        {%- set _active = "text-foreground" if pagename in url else "text-foreground/60" -%}
+        {%- if url.startswith("http") %}
+        <a href="{{ url }}" class="transition-colors hover:text-foreground/80 {{ _active }}" rel="noopener nofollow">{{
+          text }}</a>
+        {%- else %}
+        <a href="{{ pathto(url) }}" class="transition-colors hover:text-foreground/80 {{ _active }}">{{ text }}</a>
+        {%- endif %}
+        {%- endfor %}
+      </nav>
+      {%- endif %}
+      {%- endblock header_main_nav -%}
+    </div>
+    {%- endblock header_left %}
+
+    {%- block mobile_menu %}
+    {%- if sidebars|length >0 -%}
+    <button
+      class="inline-flex items-center justify-center h-10 px-0 py-2 mr-2 text-base font-medium transition-colors rounded-md hover:text-accent-foreground hover:bg-transparent md:hidden"
+      type="button" @click="showSidebar = true">
+      <svg xmlns="http://www.w3.org/2000/svg" height="24" width="24" viewBox="0 96 960 960" aria-hidden="true"
+        fill="currentColor">
+        <path
+          d="M152.587 825.087q-19.152 0-32.326-13.174t-13.174-32.326q0-19.152 13.174-32.326t32.326-13.174h440q19.152 0 32.326 13.174t13.174 32.326q0 19.152-13.174 32.326t-32.326 13.174h-440Zm0-203.587q-19.152 0-32.326-13.174T107.087 576q0-19.152 13.174-32.326t32.326-13.174h320q19.152 0 32.326 13.174T518.087 576q0 19.152-13.174 32.326T472.587 621.5h-320Zm0-203.587q-19.152 0-32.326-13.174t-13.174-32.326q0-19.152 13.174-32.326t32.326-13.174h440q19.152 0 32.326 13.174t13.174 32.326q0 19.152-13.174 32.326t-32.326 13.174h-440ZM708.913 576l112.174 112.174q12.674 12.674 12.674 31.826t-12.674 31.826Q808.413 764.5 789.261 764.5t-31.826-12.674l-144-144Q600 594.391 600 576t13.435-31.826l144-144q12.674-12.674 31.826-12.674t31.826 12.674q12.674 12.674 12.674 31.826t-12.674 31.826L708.913 576Z" />
+      </svg>
+      <span class="sr-only">Toggle navigation menu</span>
+    </button>
+    {%- endif -%}
+    {%- endblock mobile_menu %}
+
+    {%- block header_right %}
+    <div class="flex items-center justify-between flex-1 space-x-2 sm:space-x-4 md:justify-end">
+      {%- if docsearch or hasdoc('search') %}
+      <div class="flex-1 w-full md:w-auto md:flex-none">
+        {%- include "searchbox.html" %}
+      </div>
+      {%- endif %}
+
+      {%- block extra_header_link_icons %}
+      <nav class="flex items-center space-x-1">
+        <button
+            class="relative inline-flex items-center justify-center px-0 text-sm font-medium transition-colors rounded-md hover:bg-accent hover:text-accent-foreground h-9 w-9"
+            type="button"
+            onclick="window.location.href = window.location.href.indexOf('en') != -1 ? window.location.href.replace('en', 'ko') : window.location.href.replace('ko', 'en')">
+            <svg width="26px" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512"><!--!Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d="M152.1 236.2c-3.5-12.1-7.8-33.2-7.8-33.2h-.5s-4.3 21.1-7.8 33.2l-11.1 37.5H163zM616 96H336v320h280c13.3 0 24-10.7 24-24V120c0-13.3-10.7-24-24-24zm-24 120c0 6.6-5.4 12-12 12h-11.4c-6.9 23.6-21.7 47.4-42.7 69.9 8.4 6.4 17.1 12.5 26.1 18 5.5 3.4 7.3 10.5 4.1 16.2l-7.9 13.9c-3.4 5.9-10.9 7.8-16.7 4.3-12.6-7.8-24.5-16.1-35.4-24.9-10.9 8.7-22.7 17.1-35.4 24.9-5.8 3.5-13.3 1.6-16.7-4.3l-7.9-13.9c-3.2-5.6-1.4-12.8 4.2-16.2 9.3-5.7 18-11.7 26.1-18-7.9-8.4-14.9-17-21-25.7-4-5.7-2.2-13.6 3.7-17.1l6.5-3.9 7.3-4.3c5.4-3.2 12.4-1.7 16 3.4 5 7 10.8 14 17.4 20.9 13.5-14.2 23.8-28.9 30-43.2H412c-6.6 0-12-5.4-12-12v-16c0-6.6 5.4-12 12-12h64v-16c0-6.6 5.4-12 12-12h16c6.6 0 12 5.4 12 12v16h64c6.6 0 12 5.4 12 12zM0 120v272c0 13.3 10.7 24 24 24h280V96H24c-13.3 0-24 10.7-24 24zm58.9 216.1L116.4 167c1.7-4.9 6.2-8.1 11.4-8.1h32.5c5.1 0 9.7 3.3 11.4 8.1l57.5 169.1c2.6 7.8-3.1 15.9-11.4 15.9h-22.9a12 12 0 0 1 -11.5-8.6l-9.4-31.9h-60.2l-9.1 31.8c-1.5 5.1-6.2 8.7-11.5 8.7H70.3c-8.2 0-14-8.1-11.4-15.9z"/></svg>
+        </button>
+
+        <button href="https://github.com/gunyu1019/chzzkpy" title="Visit repository on GitHub" rel="noopener nofollow">
+          <div
+            class="inline-flex items-center justify-center px-0 text-sm font-medium transition-colors rounded-md disabled:opacity-50 disabled:pointer-events-none hover:bg-accent hover:text-accent-foreground h-9 w-9">
+            <svg height="26px" style="margin-top:-2px;display:inline" 
+                viewBox="0 0 45 44" 
+                fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+                <path fill-rule="evenodd" clip-rule="evenodd" 
+                d="M22.477.927C10.485.927.76 10.65.76 22.647c0 9.596 6.223 17.736 
+                14.853 20.608 1.087.2 1.483-.47 1.483-1.047 
+                0-.516-.019-1.881-.03-3.693-6.04 
+                1.312-7.315-2.912-7.315-2.912-.988-2.51-2.412-3.178-2.412-3.178-1.972-1.346.149-1.32.149-1.32 
+                2.18.154 3.327 2.24 3.327 2.24 1.937 3.318 5.084 2.36 6.321 
+                1.803.197-1.403.759-2.36 
+                1.379-2.903-4.823-.548-9.894-2.412-9.894-10.734 
+                0-2.37.847-4.31 2.236-5.828-.224-.55-.969-2.759.214-5.748 0 0 
+                1.822-.584 5.972 2.226 
+                1.732-.482 3.59-.722 5.437-.732 1.845.01 3.703.25 5.437.732 
+                4.147-2.81 5.967-2.226 
+                5.967-2.226 1.185 2.99.44 5.198.217 5.748 1.392 1.517 2.232 3.457 
+                2.232 5.828 0 
+                8.344-5.078 10.18-9.916 10.717.779.67 1.474 1.996 1.474 4.021 0 
+                2.904-.027 5.247-.027 
+                5.96 0 .58.392 1.256 1.493 1.044C37.981 40.375 44.2 32.24 44.2 
+                22.647c0-11.996-9.726-21.72-21.722-21.72" 
+                fill="currentColor"/></svg>
+          </div>
+        </a>
+
+        {%- block theme_switcher %}
+        <button @click="darkMode = darkMode === 'light' ? 'dark' : 'light'"
+          class="relative inline-flex items-center justify-center px-0 text-sm font-medium transition-colors rounded-md hover:bg-accent hover:text-accent-foreground h-9 w-9"
+          type="button"
+          aria-label="Color theme switcher">
+          <svg xmlns="http://www.w3.org/2000/svg" height="24" width="24" viewBox="0 96 960 960" fill="currentColor"
+            class="absolute transition-all scale-100 rotate-0 dark:-rotate-90 dark:scale-0">
+            <path
+              d="M480 685q45.456 0 77.228-31.772Q589 621.456 589 576q0-45.456-31.772-77.228Q525.456 467 480 467q-45.456 0-77.228 31.772Q371 530.544 371 576q0 45.456 31.772 77.228Q434.544 685 480 685Zm0 91q-83 0-141.5-58.5T280 576q0-83 58.5-141.5T480 376q83 0 141.5 58.5T680 576q0 83-58.5 141.5T480 776ZM80 621.5q-19.152 0-32.326-13.174T34.5 576q0-19.152 13.174-32.326T80 530.5h80q19.152 0 32.326 13.174T205.5 576q0 19.152-13.174 32.326T160 621.5H80Zm720 0q-19.152 0-32.326-13.174T754.5 576q0-19.152 13.174-32.326T800 530.5h80q19.152 0 32.326 13.174T925.5 576q0 19.152-13.174 32.326T880 621.5h-80Zm-320-320q-19.152 0-32.326-13.174T434.5 256v-80q0-19.152 13.174-32.326T480 130.5q19.152 0 32.326 13.174T525.5 176v80q0 19.152-13.174 32.326T480 301.5Zm0 720q-19.152 0-32.326-13.17Q434.5 995.152 434.5 976v-80q0-19.152 13.174-32.326T480 850.5q19.152 0 32.326 13.174T525.5 896v80q0 19.152-13.174 32.33-13.174 13.17-32.326 13.17ZM222.174 382.065l-43-42Q165.5 327.391 166 308.239t13.174-33.065q13.435-13.674 32.587-13.674t32.065 13.674l42.239 43q12.674 13.435 12.555 31.706-.12 18.272-12.555 31.946-12.674 13.674-31.445 13.413-18.772-.261-32.446-13.174Zm494 494.761-42.239-43q-12.674-13.435-12.674-32.087t12.674-31.565Q686.609 756.5 705.38 757q18.772.5 32.446 13.174l43 41.761Q794.5 824.609 794 843.761t-13.174 33.065Q767.391 890.5 748.239 890.5t-32.065-13.674Zm-42-494.761Q660.5 369.391 661 350.62q.5-18.772 13.174-32.446l41.761-43Q728.609 261.5 747.761 262t33.065 13.174q13.674 13.435 13.674 32.587t-13.674 32.065l-43 42.239q-13.435 12.674-31.706 12.555-18.272-.12-31.946-12.555Zm-495 494.761Q165.5 863.391 165.5 844.239t13.674-32.065l43-42.239q13.435-12.674 32.087-12.674t31.565 12.674Q299.5 782.609 299 801.38q-.5 18.772-13.174 32.446l-41.761 43Q231.391 890.5 212.239 890t-33.065-13.174ZM480 576Z" />
+          </svg>
+          <svg xmlns="http://www.w3.org/2000/svg" height="24" width="24" viewBox="0 96 960 960" fill="currentColor"
+            class="absolute transition-all scale-0 rotate-90 dark:rotate-0 dark:scale-100">
+            <path
+              d="M480 936q-151 0-255.5-104.5T120 576q0-138 90-239.5T440 218q25-3 39 18t-1 44q-17 26-25.5 55t-8.5 61q0 90 63 153t153 63q31 0 61.5-9t54.5-25q21-14 43-1.5t19 39.5q-14 138-117.5 229T480 936Zm0-80q88 0 158-48.5T740 681q-20 5-40 8t-40 3q-123 0-209.5-86.5T364 396q0-20 3-40t8-40q-78 32-126.5 102T200 576q0 116 82 198t198 82Zm-10-270Z" />
+          </svg>
+        </button>
+        {%- endblock theme_switcher %}
+      </nav>
+      {%- endblock extra_header_link_icons %}
+    </div>
+    {%- endblock header_right %}
+  </div>
+  {%- block header_after %}{%- endblock header_after %}
+</header>
diff --git a/docs/source/_templates/page.html b/docs/source/_templates/page.html
@@ -0,0 +1,29 @@
+{%- extends "layout.html" -%}
+
+{%- block body %}
+
+{%- set only_main_nav = sidebars == ["sidebar_main_nav_links.html"] %}
+{%- if not only_main_nav and sidebars|length > 0 %}
+<div class="w-full min-w-0 mx-auto">
+  {%- else %}
+  <div class="w-full min-w-0 mx-auto max-w-prose">
+    {%- endif %}
+
+    {%- block body_before %}{%- endblock body_before -%}
+
+    {%- if pagename != master_doc and theme_show_breadcrumbs|tobool %}
+    {%- include "breadcrumbs.html" %}
+    {%- endif %}
+
+    <div id="content" role="main">
+      {{ body }}
+    </div>
+
+    {%- if theme_show_prev_next|tobool %}
+      {%- include "prev_next.html" %}
+    {%- endif %}
+
+    {%- block body_after %}{%- endblock body_after -%}
+  </div>
+</div>
+{%- endblock body %}