add docs some tweaks

offish · offish · Mar 26, 2024 · Mar 20, 2024 · Mar 21, 2024 · Mar 22, 2024
commit 449e4760d19cc692c831dd92c0bd8eac0bca60dc
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,27 @@
+name: documentation
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+      - name: Install dependencies
+        run: |
+          pip install sphinx furo
+      - name: Sphinx build
+        run: |
+          sphinx-build docs _build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/
+          force_orphan: true
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,5 @@
 .vscode
 __pycache__
 jsons
-config.py
+config.py
+_build
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019-2023 offish
+Copyright (c) 2019-2024 offish
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
diff --git a/README.rst b/README.rst
@@ -0,0 +1,97 @@
+tf2-utils
+=========
+
+.. image:: https://img.shields.io/github/license/offish/tf2-utils.svg
+    :target: https://github.com/offish/tf2-utils/blob/master/LICENSE
+    :alt: License
+
+.. image:: https://img.shields.io/github/stars/offish/tf2-utils.svg
+    :target: https://github.com/offish/tf2-utils/stargazers
+    :alt: Stars
+
+.. image:: https://img.shields.io/github/issues/offish/tf2-utils.svg
+    :target: https://github.com/offish/tf2-utils/issues
+    :alt: Issues
+
+.. image:: https://img.shields.io/github/repo-size/offish/tf2-utils.svg
+    :target: https://github.com/offish/tf2-utils
+    :alt: Size
+
+.. image:: https://img.shields.io/discord/467040686982692865?color=7289da&label=Discord&logo=discord
+    :target: https://discord.gg/t8nHSvA
+    :alt: Discord
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
+    :alt: Code style
+
+.. image:: https://img.shields.io/pypi/dm/tf2-utils
+    :target: https://pypi.org/project/tf2-utils/
+    :alt: Downloads
+
+Tools and utilities for TF2 trading. Use 3rd party inventory providers, get SKUs directly from inventories, listen to BackpackTF's websocket and more.
+
+Donate
+------
+
+- BTC: ``bc1qntlxs7v76j0zpgkwm62f6z0spsvyezhcmsp0z2``
+- `Steam Trade Offer <https://steamcommunity.com/tradeoffer/new/?partner=293059984&token=0-l_idZR>`_
+
+Features
+--------
+
+- Uses `tf2-sku <https://github.com/offish/tf2-sku>`_
+- Uses `tf2-data <https://github.com/offish/tf2-data>`_
+- Get SKUs directly from inventories/offers
+- Convert name to SKU and vice versa
+- Fetch inventories using 3rd party providers (avoid being rate-limited)
+- Listen for Backpack.TF websocket events
+- Listen for Prices.TF websocket events
+- Interact with Prices.TF's API
+- Get item properties (``is_craft_hat``, ``get_paint``, ``get_effect`` etc.)
+- Fetch TF2 Schema data
+- Convert SKU/defindex to item image URL
+- Calculate scrap and refined prices
+
+
+Installing
+----------
+
+.. code-block:: bash
+
+    pip install tf2-utils
+    # or 
+    python -m pip install tf2-utils
+
+Updating
+~~~~~~~~
+
+.. code-block:: bash
+
+    pip install --upgrade tf2-utils tf2-sku tf2-data
+    # or 
+    python -m pip install --upgrade tf2-utils tf2-sku tf2-data
+
+
+Documentation
+-------------
+Documentation including usage and examples can be found `here <https://offish.github.io/tf2-utils/>`_.
+
+Development
+-----------
+
+Testing
+~~~~~~~
+.. code-block:: bash
+
+    # tf2-utils/
+    python -m unittest
+
+Documentation
+~~~~~~~~~~~~~
+.. code-block:: bash
+
+    # tf2-utils/docs/
+    pip install sphinx furo 
+    make clean # .\make.bat <command> on windows
+    make html
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     = .
+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/conf.py b/docs/conf.py
@@ -0,0 +1,66 @@
+# 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
+# flake8: noqa
+import re
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+sys.path.append(os.path.abspath("extensions"))
+
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "tf2-utils"
+copyright = "2019-2024, offish (confern)"
+author = "offish"
+
+with open("../src/tf2_utils/__init__.py") as f:
+    version = re.search(
+        r'^__version__\s*=\s*[\'"]([^\'"]*)[\'"]', f.read(), re.MULTILINE
+    ).group(1)
+
+# The full version, including alpha/beta/rc tags
+release = version
+
+# -- 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"]
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+]
+
+autodoc_member_order = "bysource"
+autodoc_mock_imports = ["requests", "websockets", "tf2_data", "tf2_sku"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True
+
+html_theme = "furo"
diff --git a/docs/index.rst b/docs/index.rst
@@ -0,0 +1,23 @@
+tf2-utils' Documentation
+========================
+
+Table of Contents
+-----------------
+.. toctree::
+   :maxdepth: 2
+
+
+   pages/backpack_tf
+   pages/currency
+   pages/inventory
+   pages/item
+   pages/marketplace_tf
+   pages/offer
+   pages/prices_tf
+   pages/schema
+   pages/sku
+   pages/sockets
+   pages/utils
+
+
+.. include:: ../README.rst