Merge pull request #2 from py-mine/add-docs

Add sphinx

.flake8

@@ -51,5 +51,6 @@ ignore=
 # ANN: All flake8-annotations errors
 per-file-ignores=
     tests/*:                    DALL000,S101,ANN
+    docs/*:                     DALL000, FA101
 
 # vi: ft=config

.github/workflows/validation.yml

@@ -28,7 +28,7 @@ jobs:
         with:
           python-version: 3.11
           poetry-version: 1.3.1
-          install-args: "--without release"
+          install-args: "--without release --with docs"
 
       - name: Pre-commit Environment Caching
         uses: actions/cache@v3

.gitignore

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

.readthedocs.yaml

@@ -0,0 +1,20 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  commands:
+    - pip install poetry
+    - poetry config virtualenvs.create false
+    - poetry install --only main,docs,docs-ci
+    - poetry run poetry-dynamic-versioning
+    - poetry run task docs
+    - mkdir ./_readthedocs
+    - mv ./docs/_build/html ./_readthedocs
+
+
+sphinx:
+  builder: dirhtml
+  configuration: "docs/conf.py"
+  fail_on_warning: true

README.md

@@ -6,6 +6,7 @@
 [![Test Coverage](https://api.codeclimate.com/v1/badges/9464f1037f07a795de35/test_coverage)](https://codeclimate.com/github/py-mine/mcproto/test_coverage)
 [![Validation](https://github.com/ItsDrike/mcproto/actions/workflows/validation.yml/badge.svg)](https://github.com/ItsDrike/mcproto/actions/workflows/validation.yml)
 [![Unit tests](https://github.com/ItsDrike/mcproto/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/ItsDrike/mcproto/actions/workflows/unit-tests.yml)
+[![Docs](https://img.shields.io/readthedocs/mcproto?label=Docs)](https://mcproto.readthedocs.io/)
 
 This is a heavily Work-In-Progress library, which attempts to be a full wrapper around the minecraft protocol, allowing
 for simple interactions with minecraft servers, and perhaps even for use as a base to a full minecraft server

changes/2.docs.md

@@ -0,0 +1 @@
+Add Sphinx and basic docs layout

docs/api/basic.rst

@@ -0,0 +1,5 @@
+Basic Usage
+===========
+
+..
+    TODO: Write this

docs/api/internal.rst

@@ -0,0 +1,10 @@
+Internal API
+============
+
+Everything listed on this page is considered internal, and is only present to provide linkable references, and
+as an easy quick reference for contributors. These components **are not a part of the public API** and **they
+should not be used externally**, as we do not guarantee their backwards compatibility, which means breaking changes
+may be introduced between patch versions without any warnings.
+
+..
+    TODO: Write this

docs/conf.py

@@ -0,0 +1,127 @@
+"""
+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
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+"""
+
+import sys
+from datetime import date
+
+from packaging.version import parse as parse_version
+
+if sys.version_info >= (3, 11):
+    from tomllib import load as toml_parse
+else:
+    from tomli import load as toml_parse
+
+
+with open("../pyproject.toml", "rb") as f:
+    pkg_meta: dict[str, str] = toml_parse(f)["tool"]["poetry"]
+
+project = str(pkg_meta["name"])
+copyright = f"{date.today().year}, ItsDrike"  # noqa: A001
+author = "ItsDrike"
+
+parsed_version = parse_version(pkg_meta["version"])
+release = str(parsed_version)
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.autosectionlabel",
+    # Used to reference for third party projects:
+    "sphinx.ext.intersphinx",
+    # Used to include .md files:
+    "m2r2",
+    # Copyable codeblocks
+    "sphinx_copybutton",
+]
+
+autoclass_content = "both"
+autodoc_member_order = "bysource"
+
+autodoc_default_flags = {
+    "members": "",
+    "undoc-members": "code,error_template",
+    "exclude-members": "__dict__,__weakref__",
+}
+
+# Automatically generate section labels:
+autosectionlabel_prefix_document = True
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+source_suffix = [".rst", ".md"]
+
+# The master toctree document.
+master_doc = "index"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+add_module_names = False
+
+autodoc_default_options = {
+    "show-inheritance": True,
+}
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+
+# -- Extension configuration -------------------------------------------------
+
+# Third-party projects documentation references:
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+
+# -- Other options -----------------------------------------------------------
+
+
+def mock_autodoc() -> None:
+    """Mock autodoc to not add ``Bases: object`` to the classes, that do not have super classes.
+
+    See also https://stackoverflow.com/a/75041544/20952782.
+    """
+    from sphinx.ext import autodoc
+
+    class MockedClassDocumenter(autodoc.ClassDocumenter):
+        def add_line(self, line: str, source: str, *lineno: int) -> None:
+            if line == "   Bases: :py:class:`object`":
+                return
+            super().add_line(line, source, *lineno)
+
+    autodoc.ClassDocumenter = MockedClassDocumenter
+
+
+mock_autodoc()

docs/examples/index.rst

@@ -0,0 +1,13 @@
+Examples
+========
+
+Here are some examples of using the project in practice.
+
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Examples
+
+    status.rst
+
+Feel free to propose any further examples, we'll be happy to add them to the list!

docs/examples/status.rst

@@ -0,0 +1,5 @@
+Obtaining status data from a server
+===================================
+
+..
+    TODO: Write this

docs/index.rst

@@ -0,0 +1,29 @@
+.. mdinclude:: ../README.md
+
+Content
+-------
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Pages
+
+    pages/installation.rst
+    examples/index.rst
+    pages/faq.rst
+    pages/contributing.rst
+    pages/code-of-conduct.rst
+
+.. toctree::
+    :maxdepth: 1
+    :caption: API Documentation
+
+    api/basic.rst
+    api/internal.rst
+
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/pages/code-of-conduct.rst

@@ -0,0 +1,11 @@
+Code of Conduct
+===============
+
+..
+    TODO: Rewrite the code of conduct here directly, rather than including it
+    like this, and just include a link to the docs in CODE-OF-CONDUCT.md
+
+    Temporarily using ``.. mdinclude:: ../../CODE-OF-CONDUCT.md`` doesn't work,
+    as it contains multiple references to same URLs,  and while m2r2 has
+    --anonymous-references option, it doesn't seem like it's possible to use it
+    with .. mdinclude

docs/pages/contributing.rst

@@ -0,0 +1,11 @@
+Contributing Guidelines
+=======================
+
+..
+    TODO: Rewrite CONTRIBUTING.md here directly, rather than including it
+    like this, and just include a link to the docs in CONTRIBUTING.md
+
+    Temporarily using ``.. mdinclude:: ../../CONTRIBUTING.md`` doesn't work,
+    as it contains multiple references to same URLs,  and while m2r2 has
+    --anonymous-references option, it doesn't seem like it's possible to use it
+    with .. mdinclude

docs/pages/faq.rst

@@ -0,0 +1,4 @@
+Frequently Asked Questions
+==========================
+
+There aren't any questions here yet. Feel free to help us change that and propose some!

docs/pages/installation.rst

@@ -0,0 +1,5 @@
+Installation
+============
+
+..
+    TODO: Write this