Move to mkdocs

.github/workflows/mkdocs.yml

@@ -0,0 +1,72 @@
+---
+name: MkDocs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.PRIVATE_KEY }}
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          token: "${{ steps.app-token.outputs.token }}"
+          # Fetch the entire git history (all branches + tags)
+          # We do this because the docs use git describe, which requires having all
+          # the commits up to the latest version tag.
+          # We also need the gh-pages branch to push the docs to.
+          fetch-depth: 0
+
+      # Make the github application be the committer
+      # (see: https://stackoverflow.com/a/74071223 on how to obtain the committer email)
+      - name: Setup git config
+        run: |
+          git config --global user.name "py-mine-ci-bot"
+          git config --global user.email "121461646+py-mine-ci-bot[bot]@users.noreply.github.com"
+
+      - name: Setup poetry
+        id: poetry_setup
+        uses: ItsDrike/setup-poetry@v1
+        with:
+          python-version: 3.12
+          install-args: "--only main,docs"
+
+      - name: Build the documentation (mkdocs - PR preview)
+        if: ${{ github.event_name == 'pull_request' }}
+        run: poetry run mkdocs build
+
+      - name: Deploy docs - PR preview
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./site
+          preview-branch: gh-pages
+          umbrella-dir: pr-preview
+          token: ${{ steps.app-token.outputs.token }}
+
+      - name: Build the documentation (mike)
+        if: ${{ github.event_name == 'push' }}
+        run: poetry run mike deploy latest
+
+      - name: Deploy docs - latest
+        if: ${{ github.event_name == 'push' }}
+        run: git push origin gh-pages

.github/workflows/publish.yml

@@ -132,3 +132,51 @@ jobs:
       # This uses PyPI's trusted publishing, so no token is required
       - name: Release to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-docs:
+    name: "Publish release docs"
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Generate token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.PRIVATE_KEY }}
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          token: "${{ steps.app-token.outputs.token }}"
+          # Fetch the entire git history (all branches + tags)
+          # We do this because the docs use git describe, which requires having all
+          # the commits up to the latest version tag.
+          # We also need the gh-pages branch to push the docs to.
+          fetch-depth: 0
+
+      # Make the github application be the committer
+      # (see: https://stackoverflow.com/a/74071223 on how to obtain the committer email)
+      - name: Setup git config
+        run: |
+          git config --global user.name "py-mine-ci-bot"
+          git config --global user.email "121461646+py-mine-ci-bot[bot]@users.noreply.github.com"
+
+      - name: Setup poetry
+        id: poetry_setup
+        uses: ItsDrike/setup-poetry@v1
+        with:
+          python-version: 3.12
+          install-args: "--only main,docs,release-ci"
+
+      - name: Set version with dynamic versioning
+        run: poetry run poetry-dynamic-versioning
+
+      - name: Build the documentation (mike)
+        run: poetry run mike deploy  --update-aliases "$(poetry version --short)" release
+
+      - name: Deploy docs - release
+        run: git push origin gh-pages

.gitignore

@@ -20,8 +20,8 @@ htmlcov/
 .coverage*
 coverage.xml
 
-# Sphinx documentation
-docs/_build/
+# Mkdocs documentation
+site/
 
 # Pyenv local version information
 .python-version

.pre-commit-config.yaml

@@ -5,6 +5,9 @@ repos:
       - id: check-merge-conflict
       - id: check-toml # For pyproject.toml
       - id: check-yaml # For workflows
+        # Only parse the files for syntax, don't do full load.
+        # We need this because of mkdocs.yml, which uses some custom tags to perform dynamic imports from python.
+        args: ["--unsafe"]
       - id: end-of-file-fixer
       - id: trailing-whitespace
         args: [--markdown-linebreak-ext=md]

ATTRIBUTION.md

@@ -1,4 +1,4 @@
-This file serves as a way to explicitly give credit to projects which made mcproto possible.
+This document serves as a way to explicitly give credit to projects which made mcproto possible.
 
 Note that as with any other project, if there was some code that was directly utilized from these projects, it will be
 mentioned in `LICENSE-THIRD-PARTY.txt`, not in here. This file isn't meant to serve as a place to disclose used code

CHANGELOG.md

@@ -4,22 +4,24 @@
 
 - [#130](https://github.com/py-mine/mcproto/issues/130): Renamed "shared_key" field to "shared_secret" in `LoginEncryptionPacket`, following the official terminology.
 
-  - This is a breaking change, `LoginEncryptionPacket`'s `__init__` method now uses "shared_secret" keyword only argument, not "shared_key".
+    - This is a breaking change, `LoginEncryptionPacket`'s `__init__` method now uses "shared_secret" keyword only argument, not "shared_key".
+
 - [#130](https://github.com/py-mine/mcproto/issues/130): The `LoginStart` packet now contains a (required) UUID field (which can be explicitly set to `None`).
-  - For some reason, this field was not added when the login packets were introduced initially, and while the UUID field can indeed be omitted in some cases (it is an optional filed), in vast majority of cases, it will be present, and we should absolutely support it.
-  - As this is a new required field, the `__init__` function of `LoginStart` now also expects this `uuid` keyword argument to be present, making this a breaking change.
+    - For some reason, this field was not added when the login packets were introduced initially, and while the UUID field can indeed be omitted in some cases (it is an optional filed), in vast majority of cases, it will be present, and we should absolutely support it.
+    - As this is a new required field, the `__init__` function of `LoginStart` now also expects this `uuid` keyword argument to be present, making this a breaking change.
 - [#159](https://github.com/py-mine/mcproto/issues/159): Fix packet compression handling in the interaction methods.
 
-  This fixes a bug that didn't allow for specifying an exact compression threshold that the server specified in `LoginSetCompression` packet, and instead only allowing to toggle between compression on/off, which doesn't really work as server doesn't expect compression for packets below that threshold.
+    This fixes a bug that didn't allow for specifying an exact compression threshold that the server specified in `LoginSetCompression` packet, and instead only allowing to toggle between compression on/off, which doesn't really work as server doesn't expect compression for packets below that threshold.
+
+    - `sync_write_packet`, `async_write_pakcet`, `sync_read_packet` and `async_read_packet` functions now take `compression_threshold` instead of `compressed` bool flag
 
-  - `sync_write_packet`, `async_write_pakcet`, `sync_read_packet` and `async_read_packet` functions now take `compression_threshold` instead of `compressed` bool flag
 - [#161](https://github.com/py-mine/mcproto/issues/161): `LoginEncryptionRequest` now uses `cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey` to hold the public key, instead of just pure `bytes`. Encoding and decoding of this key happens automatically during serialize/deserialize. This is a breaking change for anyone relying on the `public_key` field from this packet being `bytes`, and for anyone initializing this packet directly with `__init__`, which now expects `RSAPublicKey` instance instead.
 
 ### Features
 
 - [#129](https://github.com/py-mine/mcproto/issues/129): Added a system for handling Minecraft authentication
-  - Yggdrasil system for unmigrated i.e. non-Microsoft accounts (supportng Minecraft accounts, and the really old Mojang accounts)
-  - Microsoft OAuth2 system (Xbox live) for migrated i.e. Microsoft accounts
+    - Yggdrasil system for unmigrated i.e. non-Microsoft accounts (supportng Minecraft accounts, and the really old Mojang accounts)
+    - Microsoft OAuth2 system (Xbox live) for migrated i.e. Microsoft accounts
 - [#160](https://github.com/py-mine/mcproto/issues/160): Re-export the packet classes (or any other objects) from the gamestate modules (`mcproto.packets.handshaking`/`mcproto.packets.login`/...) directly. Allowing simpler imports (`from mcproto.packets.login import LoginStart` instead of `from mcproto.packets.login.login import LoginStart`)
 - [#161](https://github.com/py-mine/mcproto/issues/161): Add support for encryption. Connection classes now have `enable_encryption` method, and some encryption related functions were added into a new `mcproto.encryption` module.
 - [#168](https://github.com/py-mine/mcproto/issues/168): Add multiplayer related functionalities for requesting and checking joins for original (bought) minecraft accounts. This allows us to join online servers.
@@ -28,7 +30,7 @@
 ### Bugfixes
 
 - [#130](https://github.com/py-mine/mcproto/issues/130): `LoginEncryptionResponse` now includes the `server_id` field. This field was previously hard-coded to 20 spaces (blank value), which is what all minecraft clients on minecraft 1.7.x or higher do, however with older versions, this field is set to 20 random characters, which we should respect.
-  - This is not a breaking change, as `server_id` will default to `None` in `LoginEncryptionResponse`'s `__init__`, meaning any existing code utilizing this packet will still work. It is purely an additional option.
+    - This is not a breaking change, as `server_id` will default to `None` in `LoginEncryptionResponse`'s `__init__`, meaning any existing code utilizing this packet will still work. It is purely an additional option.
 - [#167](https://github.com/py-mine/mcproto/issues/167): Fix packet reading/writing when compression is enabled (use zlib as expected, instead of gzip which we were using before)
 - [#170](https://github.com/py-mine/mcproto/issues/170): Preserve the call parameters and overloads in the typing signature of `mcproto.packets.packet_map.generate_packet_map` function. (This wasn't the case before, since `functools.lru_cache` doesn't preserve this data). Note that this loses on the typing information about the cache itself, as now it will appear to be a regular uncached function to the type-checker. We deemed this approach better to the alternative of no typing info for call arguments or overloads, but preserving cache info.
 
@@ -39,8 +41,9 @@
 - [#141](https://github.com/py-mine/mcproto/issues/141): Move installation instructions from README to Installation docs page
 - [#144](https://github.com/py-mine/mcproto/issues/144): Add attributetable internal sphinx extension for showing all attributes and methods for specified classes.
 
-  - This adds `attributetable` sphinx directive, which can be used before autodoc directive. This will create the attribute table, which will get dynamically moved right below the class definition from autodoc (using javascript).
-  - This extension was implemented by [discord.py](https://github.com/Rapptz/discord.py/blob/2fdbe59376d736483cd1226e674e609433877af4/docs/extensions/attributetable.py), this is just re-using that code, with some modifications to fit our code style and to fit the documentation design (furo theme).
+    - This adds `attributetable` sphinx directive, which can be used before autodoc directive. This will create the attribute table, which will get dynamically moved right below the class definition from autodoc (using javascript).
+    - This extension was implemented by [discord.py](https://github.com/Rapptz/discord.py/blob/2fdbe59376d736483cd1226e674e609433877af4/docs/extensions/attributetable.py), this is just re-using that code, with some modifications to fit our code style and to fit the documentation design (furo theme).
+
 - Updated contributing guidelines (restructure and rewrite some categories, to make it more readable)
 
 ### Internal Changes
@@ -49,45 +52,43 @@
 - [#153](https://github.com/py-mine/mcproto/issues/153): Replace flake8 linter with ruff (mostly equivalent, but much faster and configurable from pyproject.toml)
 - [#154](https://github.com/py-mine/mcproto/issues/154): Enforce various new ruff linter rules:
 
-  - **PGH:** pygrep-hooks (replaces pre-commit version)
-  - **PL:** pylint (bunch of typing related linter rules)
-  - **UP:** pyupgrade (forces use of the newest possible standards, depending on target version)
-  - **RET:** flake8-return (various linter rules related to function returns)
-  - **Q:** flake8-quotes (always use double quotes)
-  - **ASYNC:** flake8-async (report blocking operations in async functions)
-  - **INT:** flake-gettext (gettext related linting rules)
-  - **PTH:** flake8-use-pathlib (always prefer pathlib alternatives to the os ones)
-  - **RUF:** ruff custom rules (various additional rules created by the ruff linter team)
+    - **PGH:** pygrep-hooks (replaces pre-commit version)
+    - **PL:** pylint (bunch of typing related linter rules)
+    - **UP:** pyupgrade (forces use of the newest possible standards, depending on target version)
+    - **RET:** flake8-return (various linter rules related to function returns)
+    - **Q:** flake8-quotes (always use double quotes)
+    - **ASYNC:** flake8-async (report blocking operations in async functions)
+    - **INT:** flake-gettext (gettext related linting rules)
+    - **PTH:** flake8-use-pathlib (always prefer pathlib alternatives to the os ones)
+    - **RUF:** ruff custom rules (various additional rules created by the ruff linter team)
 
 ---
 
-
 ## Version 0.4.0 (2023-06-11)
 
 ### Breaking Changes
 
 - [#41](https://github.com/py-mine/mcproto/issues/41): Rename `mcproto.packets.abc` to `mcproto.packets.packet`
 - [#116](https://github.com/py-mine/mcproto/issues/116): Restructure the project, moving to a single protocol version model
-  - This change does NOT have a deprecation period, and will very likely break most existing code-bases. However this change is necessary, as multi-version support was unsustainable (see issue #45 for more details)
-  - Any packets and types will no longer be present in versioned folders (mcproto.packets.v757.xxx), but rather be directly in the parent directory (mcproto.packets.xxx).
-  - This change doesn't affect manual communication with the server, connection, and basic IO writers/readers remain the same.
+    - This change does NOT have a deprecation period, and will very likely break most existing code-bases. However this change is necessary, as multi-version support was unsustainable (see issue #45 for more details)
+    - Any packets and types will no longer be present in versioned folders (mcproto.packets.v757.xxx), but rather be directly in the parent directory (mcproto.packets.xxx).
+    - This change doesn't affect manual communication with the server, connection, and basic IO writers/readers remain the same.
 
 ---
 
-
 ## Version 0.3.0 (2023-06-08)
 
 ### Features
 
 - [#54](https://github.com/py-mine/mcproto/issues/54): Add support for LOGIN state packets
-  - `LoginStart`
-  - `LoginEncryptionRequest`
-  - `LoginEncryptionResponse`
-  - `LoginSuccess`
-  - `LoginDisconnect`
-  - `LoginPluginRequest`
-  - `LoginPluginResponse`
-  - `LoginSetCompression`
+    - `LoginStart`
+    - `LoginEncryptionRequest`
+    - `LoginEncryptionResponse`
+    - `LoginSuccess`
+    - `LoginDisconnect`
+    - `LoginPluginRequest`
+    - `LoginPluginResponse`
+    - `LoginSetCompression`
 
 ### Bugfixes
 
@@ -103,9 +104,9 @@
 - [#34](https://github.com/py-mine/mcproto/issues/34): Add version guarantees page
 - [#40](https://github.com/py-mine/mcproto/issues/40): Move code of conduct to the docs.
 - Improve readability of the changelog readme (changes/README.md)
-   - Mention taskipy `changelog-preview` shorthand command
-   - Add category headers splitting things up, for better readability
-   - Explain how to express multiple changes related to a single goal in a changelog fragment.
+    - Mention taskipy `changelog-preview` shorthand command
+    - Add category headers splitting things up, for better readability
+    - Explain how to express multiple changes related to a single goal in a changelog fragment.
 - Include `CHANGELOG.md` file in project's distribution files.
 
 ### Internal Changes
@@ -121,14 +122,13 @@
 
 ---
 
-
 ## Version 0.2.0 (2022-12-30)
 
 ### Features
 
 - [#14](https://github.com/py-mine/mcproto/issues/14): Add `__slots__` to most classes in the project
-  - All connection classes are now slotted
-  - Classes in `mcproto.utils.abc` are now slotted
+    - All connection classes are now slotted
+    - Classes in `mcproto.utils.abc` are now slotted
 - Separate packet interaction functions into `mcproto.packets.interactions`, (though they're reexported in
   `mcproto.packets`, so no breaking changes)
 
@@ -147,11 +147,11 @@
 ### Internal Changes
 
 - [#6](https://github.com/py-mine/mcproto/issues/6): Rework deprecation system
-  - Drop support for date-based deprecations, versions work better
-  - Provide `deprecation_warn` function, which emits warnings directly, no need for a decorator
-  - Add a `SemanticVersion` class, supporting version comparisons
-  - If the project's version is already higher than the specified deprecation removal version, raise a DeprecationWarning
-    as a full exception (rather than just a warning).
+    - Drop support for date-based deprecations, versions work better
+    - Provide `deprecation_warn` function, which emits warnings directly, no need for a decorator
+    - Add a `SemanticVersion` class, supporting version comparisons
+    - If the project's version is already higher than the specified deprecation removal version, raise a DeprecationWarning
+      as a full exception (rather than just a warning).
 - [#7](https://github.com/py-mine/mcproto/issues/7): Add towncrier for managing changelog
 - [#14](https://github.com/py-mine/mcproto/issues/14): Add slotscheck, ensuring `__slots__` are defined properly everywhere.
 - [#14](https://github.com/py-mine/mcproto/issues/14): Make `typing-extensions` a runtime dependency and use it directly, don't rely on `if typing.TYPE_CHECKING` blocks.
@@ -164,5 +164,5 @@
 
 ---
 
-*The changelog was added during development of 0.2.0, so nothing prior is documented here. Try checking the GitHub
-releases, or git commit history directly.*
+_The changelog was added during development of 0.2.0, so nothing prior is documented here. Try checking the GitHub
+releases, or git commit history directly._

CODE-OF-CONDUCT.md

@@ -1,2 +1,2 @@
 You can find our Code of Conduct in the project's documentation
-[here](https://mcproto.readthedocs.io/en/latest/pages/code-of-conduct/)
+[here](https://py-mine.github.io/mcproto/latest/code_of_conduct/)