Build man pages (#141)

* Help text for just shell and just console

* Install sphinx and myst-parser

* Sphinxbuild hooked into justfile

* Properly generating a man page

* Remove myst-parser from dev deps

* Clean up man page copy a little

.gitignore

@@ -13,3 +13,5 @@ scratchpad.ipynb
 .tox/
 node_modules
 venv
+site
+_build

docs/conf.py

@@ -0,0 +1,22 @@
+# Configuration file for the Sphinx documentation builder.
+
+# pyee uses mkdocs for its primary documentation. However, it uses sphinx to
+# generate a man page.
+
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import toml
+
+with open("../pyproject.toml", "r") as f:
+    pyproject_toml = toml.load(f)
+
+project = "pyee"
+copyright = "2023, Josh Holbrook"
+author = "Josh Holbrook"
+release = f'v{pyproject_toml["project"]["version"]}'
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "index.md"]
+
+root_doc = "man"

docs/man.rst

@@ -0,0 +1,70 @@
+pyee
+====
+
+pyee is a rough port of
+`node.js's EventEmitter <https://nodejs.org/api/events.html>`_. Unlike its
+namesake, it includes a number of subclasses useful for implementing async
+and threaded programming in python, such as async/await as seen in python 3.5+.
+
+Install
+-------
+
+You can install this project into your environment of choice using ``pip``::
+
+    pip install pyee
+
+Usage
+-----
+
+pyee supplies a ``EventEmitter`` class that is similar to the
+``EventEmitter`` class from Node.js. In addition, it supplies subclasses for
+``asyncio``, ``twisted``, ``concurrent.futures`` and ``trio``, as supported
+by the environment.
+
+
+Example
+-------
+
+::
+
+    In [1]: from pyee.base import EventEmitter
+
+    In [2]: ee = EventEmitter()
+
+    In [3]: @ee.on('event')
+       ...: def event_handler():
+       ...:     print('BANG BANG')
+       ...:
+
+    In [4]: ee.emit('event')
+    BANG BANG
+
+    In [5]:
+
+
+API
+---
+
+pyee contains a number of modules, each intended for a different concurrency
+paradigm or framework:
+
+- ``pyee`` - synchronous ``EventEmitter``, like Node.js
+- ``pyee.asyncio`` - asyncio support
+- ``pyee.twisted`` - twisted support
+- ``pyee.executor`` - concurrent.futures support
+- ``pyee.trio`` - trio support
+
+In addition, it contains two experimental modules:
+
+- ``pyee.uplift`` - support for "uplifting" event emitters from one paradigm
+  to another - ie., adopting synchronous event emitters for use with asyncio
+- ``pyee.cls`` - support for "evented classes", which call class methods on
+  events
+
+For in-depth API documentation, visit `the docs on readthedocs.io <https://pyee.rtfd.io>`_.
+
+Links
+-----
+
+* `Fork Me On GitHub! <https://github.com/jfhbrook/pyee>`_
+* `The Docs on readthedocs.io <https://pyee.rtfd.io>`_

justfile

@@ -1,5 +1,10 @@
 set dotenv-load := true
 
+sphinx-sphinxbuild := "sphinx-build"
+sphinx-sphinxopts := ""
+sphinx-sourcedir := "docs"
+sphinx-builddir := "_build"
+
 # By default, run checks and tests, then format and lint
 default:
   if [ ! -d venv ]; then just install; fi
@@ -58,12 +63,12 @@ _clean-compile:
 
 # Format with black and isort
 format:
-  . ./venv/bin/activate &&  black './pyee' ./tests
-  . ./venv/bin/activate &&  isort --settings-file . './pyee' ./tests
+  . ./venv/bin/activate &&  black ./docs './pyee' ./tests
+  . ./venv/bin/activate &&  isort --settings-file . ./docs './pyee' ./tests
 
 # Lint with flake8
 lint:
-  . ./venv/bin/activate && flake8 './pyee' ./tests
+  . ./venv/bin/activate && flake8 ./docs './pyee' ./tests
   . ./venv/bin/activate && validate-pyproject ./pyproject.toml
 
 # Check type annotations with pyright
@@ -91,9 +96,11 @@ _clean-tox:
 # Shell and console
 #
 
+# Open a bash shell with the venv activated
 shell:
   . ./venv/bin/activate && bash
 
+# Open a Jupyter console
 console:
   . ./venv/bin/activate && jupyter console
 
@@ -105,10 +112,27 @@ console:
 docs:
   . ./venv/bin/activate && mkdocs serve
 
+# Generate man page and open for preview
+man: (sphinx 'man')
+  . ./venv/bin/activate && man -l _build/man/pyee.1
+
 # Build the documentation
 build-docs:
+  @just mkdocs
+  @just sphinx man
+
+# Run mkdocs
+mkdocs:
   . ./venv/bin/activate && mkdocs build
 
+# Run sphinx
+sphinx TARGET:
+	. ./venv/bin/activate && {{ sphinx-sphinxbuild }} -M "{{ TARGET }}" "{{ sphinx-sourcedir }}" "{{ sphinx-builddir }}" {{ sphinx-sphinxopts }}
+
+_clean-docs:
+  rm -rf site
+  rm -rf _build
+
 #
 # Package publishing
 #
@@ -132,7 +156,7 @@ upload:
 publish: build upload
 
 # Clean up loose files
-clean: _clean-venv _clean-compile _clean-test _clean-tox
+clean: _clean-venv _clean-compile _clean-test _clean-tox _clean-docs
   rm -rf pyee.egg-info
   rm -f pyee/*.pyc
   rm -rf pyee/__pycache__

pyproject.toml

@@ -46,6 +46,7 @@ dev = [
   "mkdocs",
   "mkdocs-include-markdown-plugin",
   "mkdocstrings[python]",
+  "sphinx",
   "toml",
   "tox",
   "trio",

requirements.txt

@@ -2,7 +2,7 @@
 # This file is autogenerated by pip-compile with Python 3.11
 # by the following command:
 #
-#    pip-compile --output-file=requirements.txt --resolver=backtracking pyproject.toml
+#    pip-compile --output-file=requirements.txt pyproject.toml
 #
-typing-extensions==4.6.3
+typing-extensions==4.8.0
     # via pyee (pyproject.toml)