Added ReadtheDocs documentation for the public API

- Reformatted the docstring to be compatible
- Added tests to make sure the documentation compiles properly
- Added sphinx as a pip requirement

Co-authored-by: Philip Paquette <pcpaquette@gmail.com>
Co-authored-by: notoraptor <stevenbocco@gmail.com>

29 files changed, 309 insertions, 0 deletions

diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..5117fbf
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -W --keep-going
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/theme.css b/docs/_static/theme.css
new file mode 100644
index 0000000..6c934ae
--- /dev/null
+++ b/docs/_static/theme.css
@@ -0,0 +1 @@
+.wy-nav-content { max-width: 1000px !important; }
diff --git a/docs/api/diplomacy.client.channel.rst b/docs/api/diplomacy.client.channel.rst
new file mode 100644
index 0000000..053544c
--- /dev/null
+++ b/docs/api/diplomacy.client.channel.rst
@@ -0,0 +1,6 @@
+diplomacy.client.channel
+========================
+
+.. automodule:: diplomacy.client.channel
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.client.connection.rst b/docs/api/diplomacy.client.connection.rst
new file mode 100644
index 0000000..9909466
--- /dev/null
+++ b/docs/api/diplomacy.client.connection.rst
@@ -0,0 +1,7 @@
+diplomacy.client.connection
+===========================
+
+.. automodule:: diplomacy.client.connection
+   :members:
+   :show-inheritance:
+   :exclude-members: send, write_request
diff --git a/docs/api/diplomacy.client.network_game.rst b/docs/api/diplomacy.client.network_game.rst
new file mode 100644
index 0000000..80093dd
--- /dev/null
+++ b/docs/api/diplomacy.client.network_game.rst
@@ -0,0 +1,6 @@
+diplomacy.client.network\_game
+==============================
+
+.. automodule:: diplomacy.client.network_game
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.client.rst b/docs/api/diplomacy.client.rst
new file mode 100644
index 0000000..660b82c
--- /dev/null
+++ b/docs/api/diplomacy.client.rst
@@ -0,0 +1,9 @@
+diplomacy.client
+================
+
+.. toctree::
+   :maxdepth: -1
+
+   diplomacy.client.channel
+   diplomacy.client.connection
+   diplomacy.client.network_game
diff --git a/docs/api/diplomacy.communication.notifications.rst b/docs/api/diplomacy.communication.notifications.rst
new file mode 100644
index 0000000..337035b
--- /dev/null
+++ b/docs/api/diplomacy.communication.notifications.rst
@@ -0,0 +1,6 @@
+diplomacy.communication.notifications
+=====================================
+
+.. automodule:: diplomacy.communication.notifications
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.communication.requests.rst b/docs/api/diplomacy.communication.requests.rst
new file mode 100644
index 0000000..b0ff08e
--- /dev/null
+++ b/docs/api/diplomacy.communication.requests.rst
@@ -0,0 +1,6 @@
+diplomacy.communication.requests
+================================
+
+.. automodule:: diplomacy.communication.requests
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.communication.responses.rst b/docs/api/diplomacy.communication.responses.rst
new file mode 100644
index 0000000..b34dfef
--- /dev/null
+++ b/docs/api/diplomacy.communication.responses.rst
@@ -0,0 +1,6 @@
+diplomacy.communication.responses
+=================================
+
+.. automodule:: diplomacy.communication.responses
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.communication.rst b/docs/api/diplomacy.communication.rst
new file mode 100644
index 0000000..90aa07a
--- /dev/null
+++ b/docs/api/diplomacy.communication.rst
@@ -0,0 +1,9 @@
+diplomacy.communication
+=======================
+
+.. toctree::
+   :maxdepth: -1
+
+   diplomacy.communication.notifications
+   diplomacy.communication.requests
+   diplomacy.communication.responses
diff --git a/docs/api/diplomacy.daide.notifications.rst b/docs/api/diplomacy.daide.notifications.rst
new file mode 100644
index 0000000..1c5251b
--- /dev/null
+++ b/docs/api/diplomacy.daide.notifications.rst
@@ -0,0 +1,6 @@
+diplomacy.daide.notifications
+=============================
+
+.. automodule:: diplomacy.daide.notifications
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.daide.requests.rst b/docs/api/diplomacy.daide.requests.rst
new file mode 100644
index 0000000..86782be
--- /dev/null
+++ b/docs/api/diplomacy.daide.requests.rst
@@ -0,0 +1,6 @@
+diplomacy.daide.requests
+========================
+
+.. automodule:: diplomacy.daide.requests
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.daide.responses.rst b/docs/api/diplomacy.daide.responses.rst
new file mode 100644
index 0000000..b8d46d0
--- /dev/null
+++ b/docs/api/diplomacy.daide.responses.rst
@@ -0,0 +1,6 @@
+diplomacy.daide.responses
+=========================
+
+.. automodule:: diplomacy.daide.responses
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.daide.rst b/docs/api/diplomacy.daide.rst
new file mode 100644
index 0000000..ff8a23d
--- /dev/null
+++ b/docs/api/diplomacy.daide.rst
@@ -0,0 +1,9 @@
+diplomacy.daide
+===============
+
+.. toctree::
+   :maxdepth: -1
+
+   diplomacy.daide.notifications
+   diplomacy.daide.requests
+   diplomacy.daide.responses
diff --git a/docs/api/diplomacy.engine.game.rst b/docs/api/diplomacy.engine.game.rst
new file mode 100644
index 0000000..c6bcb05
--- /dev/null
+++ b/docs/api/diplomacy.engine.game.rst
@@ -0,0 +1,6 @@
+diplomacy.engine.game
+=====================
+
+.. automodule:: diplomacy.engine.game
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.engine.map.rst b/docs/api/diplomacy.engine.map.rst
new file mode 100644
index 0000000..4f5514d
--- /dev/null
+++ b/docs/api/diplomacy.engine.map.rst
@@ -0,0 +1,6 @@
+diplomacy.engine.map
+====================
+
+.. automodule:: diplomacy.engine.map
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.engine.message.rst b/docs/api/diplomacy.engine.message.rst
new file mode 100644
index 0000000..98f8a25
--- /dev/null
+++ b/docs/api/diplomacy.engine.message.rst
@@ -0,0 +1,6 @@
+diplomacy.engine.message
+========================
+
+.. automodule:: diplomacy.engine.message
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.engine.power.rst b/docs/api/diplomacy.engine.power.rst
new file mode 100644
index 0000000..655c231
--- /dev/null
+++ b/docs/api/diplomacy.engine.power.rst
@@ -0,0 +1,6 @@
+diplomacy.engine.power
+======================
+
+.. automodule:: diplomacy.engine.power
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.engine.renderer.rst b/docs/api/diplomacy.engine.renderer.rst
new file mode 100644
index 0000000..c150229
--- /dev/null
+++ b/docs/api/diplomacy.engine.renderer.rst
@@ -0,0 +1,6 @@
+diplomacy.engine.renderer
+=========================
+
+.. automodule:: diplomacy.engine.renderer
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.engine.rst b/docs/api/diplomacy.engine.rst
new file mode 100644
index 0000000..4fc098f
--- /dev/null
+++ b/docs/api/diplomacy.engine.rst
@@ -0,0 +1,11 @@
+diplomacy.engine
+================
+
+.. toctree::
+   :maxdepth: -1
+
+   diplomacy.engine.game
+   diplomacy.engine.map
+   diplomacy.engine.message
+   diplomacy.engine.power
+   diplomacy.engine.renderer
diff --git a/docs/api/diplomacy.integration.rst b/docs/api/diplomacy.integration.rst
new file mode 100644
index 0000000..2625bb6
--- /dev/null
+++ b/docs/api/diplomacy.integration.rst
@@ -0,0 +1,6 @@
+diplomacy.integration
+=====================
+
+.. toctree::
+
+    diplomacy.integration.webdiplomacy_net.api
diff --git a/docs/api/diplomacy.integration.webdiplomacy_net.api.rst b/docs/api/diplomacy.integration.webdiplomacy_net.api.rst
new file mode 100644
index 0000000..8478615
--- /dev/null
+++ b/docs/api/diplomacy.integration.webdiplomacy_net.api.rst
@@ -0,0 +1,6 @@
+integration.webdiplomacy\_net.api
+=================================
+
+.. automodule:: diplomacy.integration.webdiplomacy_net.api
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.utils.errors.rst b/docs/api/diplomacy.utils.errors.rst
new file mode 100644
index 0000000..82fd9ee
--- /dev/null
+++ b/docs/api/diplomacy.utils.errors.rst
@@ -0,0 +1,6 @@
+diplomacy.utils.errors
+======================
+
+.. automodule:: diplomacy.utils.errors
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.utils.exceptions.rst b/docs/api/diplomacy.utils.exceptions.rst
new file mode 100644
index 0000000..e948ed4
--- /dev/null
+++ b/docs/api/diplomacy.utils.exceptions.rst
@@ -0,0 +1,6 @@
+diplomacy.utils.exceptions
+==========================
+
+.. automodule:: diplomacy.utils.exceptions
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.utils.export.rst b/docs/api/diplomacy.utils.export.rst
new file mode 100644
index 0000000..afbb9d6
--- /dev/null
+++ b/docs/api/diplomacy.utils.export.rst
@@ -0,0 +1,6 @@
+diplomacy.utils.export
+======================
+
+.. automodule:: diplomacy.utils.export
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.utils.order_results.rst b/docs/api/diplomacy.utils.order_results.rst
new file mode 100644
index 0000000..98bee71
--- /dev/null
+++ b/docs/api/diplomacy.utils.order_results.rst
@@ -0,0 +1,6 @@
+diplomacy.utils.order\_results
+==============================
+
+.. automodule:: diplomacy.utils.order_results
+   :members:
+   :show-inheritance:
diff --git a/docs/api/diplomacy.utils.rst b/docs/api/diplomacy.utils.rst
new file mode 100644
index 0000000..2e775ef
--- /dev/null
+++ b/docs/api/diplomacy.utils.rst
@@ -0,0 +1,10 @@
+diplomacy.utils
+===============
+
+.. toctree::
+   :maxdepth: -1
+
+   diplomacy.utils.errors
+   diplomacy.utils.exceptions
+   diplomacy.utils.export
+   diplomacy.utils.order_results
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..10f8f40
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,77 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+from datetime import datetime
+
+# -- Project information -----------------------------------------------------
+
+project = 'diplomacy'
+author = 'Philip Paquette'
+copyright = str(datetime.now().year) + ' - ' + author
+
+# The full version, including alpha/beta/rc tags
+version = 'latest'
+release = 'latest'
+
+# -- General configuration ---------------------------------------------------
+autodoc_member_order = 'bysource'
+master_doc = 'index'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx_copybutton',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.viewcode',
+    'sphinx_rtd_theme',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# 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']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+
+# Make sure __init__ methods are documented by defining a setup method which
+# calls a skip method. It seems setup method id automatically called by sphinx.
+# Source (2019/08/19): https://stackoverflow.com/a/5599712
+
+def skip(app, what, name, obj, would_skip, options):
+    del app, what, options
+    if name == "__init__" and obj.__doc__ and obj.__doc__.strip():
+        return False
+    return would_skip
+
+def setup(app):
+    app.add_stylesheet('theme.css')
+    app.connect("autodoc-skip-member", skip)
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..5fda49c
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,42 @@
+Welcome to Diplomacy package!
+=============================
+
+Diplomacy is a strategic board game when you play a country (power) on a map with the goal to conquer at least half to
+all the supply centers present on the map. To achieve this goal, you control power units (armies and/or fleets) that
+you can use to occupy empty provinces (locations), attack provinces occupied by other powers, or support other units
+occupying or attacking a position.
+
+This is a complex game with many rules and corner cases to take into account, and, thus, an interesting subject for
+both entertainment (between humans) and studies (e.g. how to create an artificial intelligence good enough to beat
+humans). This project aims to provide a complete and working Python implementation of Diplomacy game with following
+features:
+
+- A working game engine easy to use to get familiar with game rules, test corner cases, and simulate complete parties.
+- An interface to allow the game to be played online, using:
+
+  - a Python server implementation to handle many games
+  - a Python client implementation to play remotely using all the power and facilities of Python
+  - a web front-end to play remotely using a human user-friendly interface
+
+- Some integration interface to play with other server/client implementations, especially:
+
+  - a DAIDE server to play with DAIDE client bots
+  - a webdiplomacy API to play with `webdiplomacy <http://webdiplomacy.net/>`_ server implementation
+
+.. toctree::
+   :maxdepth: -1
+   :caption: API Documentation
+
+   api/diplomacy.client
+   api/diplomacy.communication
+   api/diplomacy.daide
+   api/diplomacy.engine
+   api/diplomacy.integration
+   api/diplomacy.utils
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`