diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e60fef8..49513f0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -11,9 +11,11 @@ on: push: branches: [ 'master', 'main' ] + tags: + - 'v*' concurrency: - group: ${{ github.head_ref || github.ref }} + group: ${{ github.head_ref || github.run_id }} cancel-in-progress: true jobs: @@ -31,7 +33,7 @@ jobs: - name: Run pre-commit uses: pre-commit/action@v3.0.0 - tox: + test: runs-on: ubuntu-latest steps: - name: Checkout Code Repository @@ -53,3 +55,29 @@ jobs: with: token: ${{ secrets.CODECOV_TOKEN }} fail_ci_if_error: true + + publish: + runs-on: ubuntu-latest + needs: [linter, test] + if: startsWith(github.ref, 'refs/tags/v') + steps: + - uses: actions/checkout@v2 + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: '3.x' + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install build setuptools wheel twine + - name: Build a binary wheel and a source tarball + run: >- + python -m + build + --sdist + --wheel + --outdir dist/ + - name: Build and publish 📦 to PyPI + uses: pypa/gh-action-pypi-publish@master + with: + password: ${{ secrets.PYPI_API_TOKEN }} diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml deleted file mode 100644 index 2442bf3..0000000 --- a/.github/workflows/publish.yml +++ /dev/null @@ -1,33 +0,0 @@ -name: Publish - -on: - push: - tags: - - '*' - -jobs: - publish: - runs-on: ubuntu-latest - needs: [linter, tox] - steps: - - uses: actions/checkout@v2 - - name: Set up Python - uses: actions/setup-python@v2 - with: - python-version: '3.x' - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install build setuptools wheel twine - - name: Build a binary wheel and a source tarball - run: >- - python -m - build - --sdist - --wheel - --outdir dist/ - - name: Build and publish 📦 to PyPI - if: startsWith(github.ref, 'refs/tags') - uses: pypa/gh-action-pypi-publish@master - with: - password: ${{ secrets.PYPI_API_TOKEN }} diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..961b7e4 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,32 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + # You can also specify other tool versions: + # nodejs: "19" + # rust: "1.64" + # golang: "1.19" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: requirements/develop.txt diff --git a/README.md b/README.md index 13b88d3..e5d0ae8 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,13 @@ -# boardgamegeek +# BGG-API ### A Python API for [boardgamegeek.com](https://boardgamegeek.com/) +[![docs status](https://readthedocs.org/projects/bgg-api/badge/?version=latest)](https://bgg-api.readthedocs.io/en/latest/) [![ci workflow status](https://github.com/SukiCZ/boardgamegeek/actions/workflows/ci.yml/badge.svg)](https://github.com/SukiCZ/boardgamegeek/actions) [![codecov](https://codecov.io/gh/SukiCZ/boardgamegeek/graph/badge.svg?token=LMOWZ62OIS)](https://codecov.io/gh/SukiCZ/boardgamegeek) -[![Black code style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black) +[![Black code style](https://img.shields.io/badge/code_style-black-000000.svg)](https://github.com/ambv/black) +![Contributions welcome](https://img.shields.io/badge/contributions-welcome-green.svg) ## Installation @@ -44,13 +46,7 @@ tox ```bash # Bump version (patch, minor, major) -bumpversion patch +bump2version patch # Push to github git push --tags origin master ``` - - -## Documentation - - -Documentation is available at diff --git a/docs/changelog.rst b/docs/changelog.rst index 69f615a..8238e10 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -2,6 +2,14 @@ Changelog ========= +1.1.1 +----- + +* Upgrade Sphinx documentation +* Publish documentation to `readthedocs.io `_ +* Initialize Github Publish Action + + 1.1.0 ----- diff --git a/docs/conf.py b/docs/conf.py index 6945eb4..34e1a57 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -36,13 +36,19 @@ 'sphinx.ext.coverage', 'sphinx.ext.imgmath', 'sphinx.ext.viewcode', + + 'myst_parser', # Markdown support ] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix of source filenames. -source_suffix = '.rst' +source_suffix = { + '.rst': 'restructuredtext', + '.txt': 'markdown', + '.md': 'markdown', +} # The encoding of source files. #source_encoding = 'utf-8-sig' @@ -51,8 +57,8 @@ master_doc = 'index' # General information about the project. -project = u'boardgamegeek' -copyright = u'2014, Cosmin Luță' +project = u'bgg-api' +copyright = u'2024, Jakub Boukal' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -106,7 +112,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphinxdoc' +html_theme = 'alabaster' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/index.rst b/docs/index.rst index c184ba8..4986048 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,8 @@ -================================================== -boardgamegeek - A Python API for boardgamegeek.com -================================================== +======= +BGG-API +======= + +A Python API wrapper for BoardGameGeek_ .. note:: @@ -11,10 +13,9 @@ Introduction ============ -``boardgamegeek`` is a Python library which makes it easy to access data from BoardGameGeek_ using their official XML -API. +``bgg-api`` is a Python wrapper to easily access data from BoardGameGeek_ XML API. -It's an almost completely rewritten fork of libBGG_. +It's continuation of boardgamegeek2_, which is an almost completely rewritten fork of libBGG_. Table of Contents ================= @@ -22,16 +23,17 @@ Table of Contents .. toctree:: :maxdepth: 2 - changelog modules + changelog + Features ======== This library exposes (as Python objects with properties) the following BoardGameGeek_ entities: -* Users * Games +* Users * User collections * Player guilds * Plays @@ -44,39 +46,30 @@ requests-cache_ is used for locally caching replies in order to reduce the amoun persistent cache. -Quick Install -============= - -To install ``boardgamegeek``, just use pip:: - - > pip install boardgamegeek2 - -If you had previously used this library before it was rewritten, you'll need to uninstall it first:: +Installation +============ - > pip uninstall boardgamegeek +.. code-block:: shell + pip install bgg-api Usage ===== -Here's a quick usage example: +.. code-block:: python -.. code-block:: pycon + from boardgamegeek import BGGClient - >>> from boardgamegeek import BGGClient - >>> bgg = BGGClient() - >>> g = bgg.game("Android: Netrunner") - >>> g.name - 'Android: Netrunner' - >>> g.id - 124742 - >>> for n in g.alternative_names: print n.encode("utf-8") - ... - 安卓纪元：矩阵潜袭 + bgg = BGGClient() + game = bgg.game("Monopoly") -To Do -===== + print(game.year) # 1935 + print(game.rating_average) # 4.36166 + + +TODO +==== * Not all the information exposed by the official API is stored into the Python objects. Need to improve this. * Try to support the other sites from the boardgamegeek's family @@ -91,6 +84,7 @@ Credits Original authors: +* Cosmin Luță (github:lcosmin) * Phil S. Stein (github:philsstein) * Geoff Lawler (github:glawler) @@ -113,5 +107,6 @@ Indices and tables * :ref:`search` .. _BoardGameGeek: http://www.boardgamegeek.com +.. _boardgamegeek2: https://github.com/lcosmin/boardgamegeek .. _libBGG: https://github.com/philsstein/libBGG .. _requests-cache: https://pypi.python.org/pypi/requests-cache diff --git a/requirements/develop.txt b/requirements/develop.txt index f52814b..bee9c5b 100644 --- a/requirements/develop.txt +++ b/requirements/develop.txt @@ -4,6 +4,7 @@ bump2version==1.0.1 wheel==0.42 tox==4.12.0 Sphinx==7.2.6 +myst-parser==2.0.0 twine==4.0.2 pytest==7.4.4 pytest-mock==3.12.0