style(documentation): switch to mkdocs from sphinx

Makefile

@@ -8,18 +8,14 @@ TOX ?= tox
 NOSETESTS ?= nosetests
 ICONV ?= iconv
 MYPY ?= mypy
-SPHINX2RST ?= sphinx2rst
 
 TESTDIR ?= t
-SPHINX_DIR ?= docs/
-SPHINX_BUILDDIR ?= "${SPHINX_DIR}/_build"
 README ?= README.rst
 README_SRC ?= "docs/templates/readme.txt"
 CONTRIBUTING ?= CONTRIBUTING.rst
 CONTRIBUTING_SRC ?= "docs/contributing.rst"
 COC ?= CODE_OF_CONDUCT.rst
 COC_SRC ?= "docs/includes/code-of-conduct.txt"
-SPHINX_HTMLDIR="${SPHINX_BUILDDIR}/html"
 DOCUMENTATION=Documentation
 
 all: help
@@ -55,19 +51,15 @@ release:
 
 . PHONY: deps-default
 deps-default:
-	$(PIP) install -U -r requirements/default.txt
-
-. PHONY: deps-dist
-deps-dist:
-	$(PIP) install -U -r requirements/dist.txt
+	$(PIP) install -U -e "."
 
 . PHONY: deps-docs
 deps-docs:
-	$(PIP) install -U -r requirements/docs.txt
+	$(PIP) install -U -r requirements-docs.txt
 
 . PHONY: deps-test
 deps-test:
-	$(PIP) install -U -r requirements/test.txt
+	$(PIP) install -U -r requirements-test.txt
 
 . PHONY: deps-extras
 deps-extras:
@@ -80,12 +72,15 @@ develop: deps-default deps-dist deps-docs deps-test deps-extras
 
 . PHONY: Documentation
 Documentation:
-	(cd "$(SPHINX_DIR)"; $(MAKE) html)
-	mv "$(SPHINX_HTMLDIR)" $(DOCUMENTATION)
+	mkdocs build
 
 . PHONY: docs
 docs: Documentation
 
+. PHONE: serve-docs
+serve-docs:
+	mkdocs serve
+
 clean-docs:
 	-rm -rf "$(SPHINX_BUILDDIR)"
 
@@ -94,34 +89,22 @@ ruff:
 
 lint: ruff apicheck readmecheck
 
-apicheck:
-	(cd "$(SPHINX_DIR)"; $(MAKE) apicheck)
-
 clean-readme:
 	-rm -f $(README)
 
 readmecheck:
 	$(ICONV) -f ascii -t ascii $(README) >/dev/null
 
-$(README):
-	$(SPHINX2RST) "$(README_SRC)" --ascii > $@
-
 readme: clean-readme $(README) readmecheck
 
 clean-contrib:
 	-rm -f "$(CONTRIBUTING)"
 
-$(CONTRIBUTING):
-	$(SPHINX2RST) "$(CONTRIBUTING_SRC)" > $@
-
 contrib: clean-contrib $(CONTRIBUTING)
 
 clean-coc:
 	-rm -f "$(COC)"
 
-$(COC):
-	$(SPHINX2RST) "$(COC_SRC)" > $@
-
 coc: clean-coc $(COC)
 
 clean-pyc:
@@ -161,9 +144,4 @@ typecheck:
 .PHONY: requirements
 requirements:
 	$(PIP) install --upgrade pip;\
-	for f in `ls requirements/` ; do $(PIP) install -r requirements/$$f ; done
-
-.PHONY: clean-requirements
-clean-requirements:
-	pip freeze | xargs pip uninstall -y
-	$(MAKE) requirements
+	$(PIP) install -r requirements.txt

docs/creating-service.md

@@ -0,0 +1,102 @@
+
+# Creating a Service
+
+To define a service, simply subclass and fill in the methods
+to do stuff as the service is started/stopped etc.:
+
+```python
+class MyService(Service):
+
+    async def on_start(self) -> None:
+        print('Im starting now')
+
+    async def on_started(self) -> None:
+        print('Im ready')
+
+    async def on_stop(self) -> None:
+        print('Im stopping now')
+```
+
+To start the service, call ``await service.start()``:
+
+```python
+await service.start()
+```
+
+Or you can use ``mode.Worker`` (or a subclass of this) to start your
+services-based asyncio program from the console:
+
+```python
+if __name__ == '__main__':
+    import mode
+    worker = mode.Worker(
+        MyService(),
+        loglevel='INFO',
+        logfile=None,
+        daemon=False,
+    )
+    worker.execute_from_commandline()
+```
+
+## It's a Graph!
+
+Services can start other services, coroutines, and background tasks.
+
+1) Starting other services using ``add_dependency``:
+
+```python
+ class MyService(Service):
+
+     def __post_init__(self) -> None:
+        self.add_dependency(OtherService(loop=self.loop))
+```
+
+1) Start a list of services using ``on_init_dependencies``:
+
+```python
+class MyService(Service):
+
+    def on_init_dependencies(self) -> None:
+        return [
+            ServiceA(loop=self.loop),
+            ServiceB(loop=self.loop),
+            ServiceC(loop=self.loop),
+        ]
+```
+
+1) Start a future/coroutine (that will be waited on to complete on stop):
+
+```python
+ class MyService(Service):
+
+     async def on_start(self) -> None:
+         self.add_future(self.my_coro())
+
+     async def my_coro(self) -> None:
+         print('Executing coroutine')
+```
+
+1) Start a background task:
+
+```python
+class MyService(Service):
+
+    @Service.task
+    async def _my_coro(self) -> None:
+        print('Executing coroutine')
+```
+
+
+1) Start a background task that keeps running:
+
+```python
+class MyService(Service):
+
+    @Service.task
+    async def _my_coro(self) -> None:
+        while not self.should_stop:
+            # NOTE: self.sleep will wait for one second, or
+            #       until service stopped/crashed.
+            await self.sleep(1.0)
+            print('Background thread waking up')
+```