Upgrade Sphinx documentation

.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/[email protected]
 
-  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 }}

.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

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
-<!-- TODO Restructure docs, publish to readthedocs.io -->
-
-Documentation is available at <http://lcosmin.github.io/boardgamegeek>

docs/changelog.rst

@@ -2,6 +2,14 @@ Changelog
 =========
 
 
+1.1.1
+-----
+
+* Upgrade Sphinx documentation
+* Publish documentation to `readthedocs.io <https://bgg-api.readthedocs.io>`_
+* Initialize Github Publish Action
+
+
 1.1.0
 -----
 

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

docs/index.rst

@@ -1,6 +1,8 @@
-==================================================
-boardgamegeek - A Python API for boardgamegeek.com
-==================================================
+=======
+BGG-API
+=======
+
+A Python API wrapper for BoardGameGeek_
 
 .. note::
 
@@ -11,27 +13,27 @@ 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
 =================
 
 .. 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

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