Merge pull request #102 from nonowazu/feat/rtd

Migrate docs from pdoc3 to basic RTD

.editorconfig

@@ -18,3 +18,8 @@ trim_trailing_whitespace = false
 [*.py]
 indent_size = 4
 indent_style = space
+
+[*.rst]
+max_line_length = 80
+indent_style = space
+indent_size = 4

.gitignore

@@ -76,8 +76,8 @@ coverage.xml
 # Scrapy stuff:
 .scrapy
 
-# Documentation
-docs/
+# Docs
+docs/build/*
 
 # PyBuilder
 target/

.vscode/extensions.json

@@ -1,7 +1,8 @@
 {
 	"recommendations": [
-        "ms-python.python",
-        "ms-python.vscode-pylance",
-        "EditorConfig.EditorConfig"
-	]
+                "ms-python.python",
+                "ms-python.vscode-pylance",
+                "editorconfig.editorconfig",
+                "njpwerner.autodocstring"
+        ]
 }

.vscode/settings.json

@@ -8,4 +8,5 @@
     "**/__pycache__": true,
     "**/.venv": true
   },
+  "esbonio.sphinx.confDir": "docs/source",
 }

docs/Makefile

@@ -0,0 +1,17 @@
+# Sphinx documentation
+
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = source
+BUILDDIR = build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/conf.py

@@ -0,0 +1,21 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../../")) # Where the module is located
+
+from nari import __version__ as nari_version
+
+project = 'nari'
+copyright = '2020, Oowazu Nonowazu'
+author = 'Oowazu Nonowazu'
+
+release = '0.1.0' # TODO: figure out how to automate this later - gh action?
+version = nari_version
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'myst_parser'
+]
+
+autodoc_typehints = 'description'
+html_theme = 'sphinx_rtd_theme'

docs/source/events.rst

@@ -0,0 +1,72 @@
+Events
+======
+
+Nari's core concept revolves around events, which represent various happenings
+in and around Final Fantasy XIV. The most basic Event is (appropriately) named
+``Event``
+
+.. automodule:: nari.types.event
+    :members:
+
+.. automodule:: nari.types.event.ability
+    :members:
+
+.. automodule:: nari.types.event.actorspawn
+    :members:
+
+.. automodule:: nari.types.event.cast
+    :members:
+
+.. automodule:: nari.types.event.config
+    :members:
+
+.. automodule:: nari.types.event.death
+    :members:
+
+.. automodule:: nari.types.event.effectresult
+    :members:
+
+.. automodule:: nari.types.event.gauge
+    :members:
+
+.. automodule:: nari.types.event.instance
+    :members:
+
+.. automodule:: nari.types.event.limitbreak
+    :members:
+
+.. automodule:: nari.types.event.markers
+    :members:
+
+.. automodule:: nari.types.event.party
+    :members:
+
+.. automodule:: nari.types.event.playerstats
+    :members:
+
+.. automodule:: nari.types.event.status
+    :members:
+
+.. automodule:: nari.types.event.statuslist
+    :members:
+
+.. automodule:: nari.types.event.tether
+    :members:
+
+.. automodule:: nari.types.event.ticks
+    :members:
+
+.. automodule:: nari.types.event.updatehpmp
+    :members:
+
+.. automodule:: nari.types.event.version
+    :members:
+
+.. automodule:: nari.types.event.visibility
+    :members:
+
+.. automodule:: nari.types.event.waymark
+    :members:
+
+.. automodule:: nari.types.event.zone
+    :members:

docs/source/index.md

@@ -0,0 +1,17 @@
+# NARI
+
+
+**NARI** (Nonowazu ACT Reference Implementation) is a python library to
+generate event data from Final Fantasy FFXIV sources, such as ACT.
+
+
+Take a look the [overview](overview) at for more information, or hop over to how to [install](installation) nari.
+
+
+```{toctree}
+:maxdepth: 1
+installation
+overview
+events
+readers
+```

docs/source/installation.rst

@@ -0,0 +1,24 @@
+Installation
+============
+
+Python Version
+--------------
+
+Since we use some annotation features and structural pattern matching, the
+only supported version is Python 3.10 or newer.
+
+
+Install nari
+------------
+
+To install nari using pip:
+
+.. code-block:: sh
+
+    $ pip install nari
+
+To install nari from the github repo:
+
+.. code-block:: sh
+
+    $ pip install git+https://github.com/xivlogs/nari.git@master#egg=nari

docs/source/overview.rst

@@ -0,0 +1,61 @@
+Overview
+========
+
+nari revolves around 3 core concepts:
+
+1. Events
+2. Readers, which generate those events
+3. Writers, which consume those events
+
+Events
+~~~~~~
+
+The core of nari is its abstract events - events which represent various events
+that happen in the game. While nari's core focuses on combat-focused events,
+nothing stops a developer from subclassing Event and adding event types for
+any type of action in the game (crafting, gathering, retainer actions, etc)
+
+Readers
+~~~~~~~
+
+For a basic example of using readers, look at the `act extension <https://github.com/xivlogs/nari-act>`_:
+
+.. code-block:: python
+
+    from nari.ext.act import ActLogReader
+
+    for event in ActLogReader('/path/to/act.log'):
+        print(event)
+
+All readers are iterators inherently, so you can use it in any python
+function/method that consumes iterators.
+
+.. caution::
+
+    Some readers, like nari-act, can only consume the data one time before
+    creating another instance; double-check the reader documentation before
+    trying to use other iterator features (like slices)
+
+Writers
+~~~~~~~
+
+Writers are as straightforward as readers in that they consume an iterator
+which returns an event. You *could* hook up a reader directly to a writer in
+order to change file formats, for example:
+
+.. code-block:: python
+
+    from nari.ext.act import ActLogReader
+    from nari.io.writer.pickle import PickleWriter
+
+    PickleWriter(ActLogReader('/path/to/act.log')).write()
+
+You could also hand generate events and write those using a writer:
+
+.. code-block:: python
+
+    from nari.types.event import Event
+    from nari.io.writer.pickle import PickleWriter
+
+    events = [Event(timestamp=1), Event(timestamp=2), Event(timestamp=3)]
+    PickleWriter(events).write()