Add auto documentation with pdoc3 (#748)

* Add pdoc3 to dev dependencies

* Build docs in github actions

* Add docstrings to empty __init__.py files

Pdoc errors out on empty files.

* Use typing.NamedTuple

pdoc3 can't get source code for it otherwise

.github/workflows/doc.yml

@@ -0,0 +1,32 @@
+# Build the documentation and push to github pages
+name: Doc
+
+on:
+  push:
+    branches: develop
+
+jobs:
+  deploy:
+    runs-on: ubuntu-18.04
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: 3.7
+
+      - name: Install dependencies with pipenv
+        run: |
+          pip install pipenv
+          pipenv sync
+          pipenv run pip install pdoc3
+
+      - name: Build
+        run: pipenv run doc
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./html/server

.github/workflows/test.yml

@@ -1,7 +1,12 @@
 # Run unit tests
 name: Test
 
-on: [push, pull_request]
+on:
+  push:
+    branches:
+      - master
+      - develop
+  pull_request:
 
 env:
   FAF_DB_VERSION: v112
@@ -75,6 +80,9 @@ jobs:
           files: coverage.xml
           fail_ci_if_error: true
 
+      - name: Check documentation
+        run: PYTHONWARNINGS='error::UserWarning' pipenv run pdoc3 server >/dev/null
+
   docker-build:
       runs-on: ubuntu-latest
       steps:

Pipfile

@@ -3,6 +3,7 @@ devserver = "python server.py --configuration-file dev-config.yml"
 tests = "py.test --cov-report term-missing --cov=server --mysql_database=faf -o testpaths=tests"
 integration = "py.test -o testpaths=integration_tests"
 vulture = "vulture server.py server/ --sort-by-size"
+doc = "pdoc3 --html --force server"
 
 [[source]]
 url = "https://pypi.org/simple"
@@ -34,6 +35,7 @@ mock = "*"
 vulture = "*"
 asynctest = "*"
 hypothesis = "*"
+pdoc3 = "*"
 
 [requires]
 python_version = "3.7"

server/abc/__init__.py

@@ -0,0 +1,3 @@
+"""
+Abstract base classes
+"""

server/api/__init__.py

@@ -0,0 +1,3 @@
+"""
+API connector
+"""

server/games/__init__.py

@@ -1,4 +1,4 @@
-from collections import namedtuple
+from typing import NamedTuple
 
 from .coop import CoopGame
 from .custom_game import CustomGame
@@ -12,10 +12,14 @@
     VisibilityState
 )
 
-FeaturedMod = namedtuple(
-    "FeaturedMod",
-    "id name full_name description publish order"
-)
+
+class FeaturedMod(NamedTuple):
+    id: int
+    name: str
+    full_name: str
+    description: str
+    publish: bool
+    order: int
 
 
 __all__ = (

server/ice_servers/__init__.py

@@ -0,0 +1,3 @@
+"""
+ICE server configuration
+"""