Added doc framework

coordt · coordt · commit 539f351b1afb · 2024-03-17T08:11:20.000-05:00
diff --git a/docs/assets/chr_logo.png b/docs/assets/chr_logo.png
diff --git a/docs/assets/extra.css b/docs/assets/extra.css
@@ -0,0 +1,54 @@
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: .05rem solid var(--md-typeset-table-color);
+}
+
+/* Normal size fonts on parameter tables */
+.md-typeset div.doc-contents table {
+  font-size: 1em;
+  width: 100%;
+  display: table;
+}
+
+/* Mark external links as such. */
+a.autorefs-external::after {
+  /* https://primer.style/octicons/arrow-up-right-24 */
+  background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="rgb(0, 0, 0)" d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: ' ';
+
+  display: inline-block;
+  vertical-align: middle;
+  position: relative;
+  bottom: 0.1em;
+  margin-left: 0.2em;
+  margin-right: 0.1em;
+
+  height: 0.7em;
+  width: 0.7em;
+  border-radius: 100%;
+  background-color: var(--md-typeset-a-color);
+}
+a.autorefs-external:hover::after {
+  background-color: var(--md-accent-fg-color);
+}
+span.doc-param-annotation:first-child{
+  border-top: 1px solid var(--md-typeset-table-color);
+  padding-top: 5px;
+  margin-top: 5px;
+  margin-bottom: -5px;
+}
+span.doc-param-annotation {
+  font-size: 0.8em;
+  display: block;
+}
+span.doc-param-default {
+  font-size: 0.8em;
+  float: unset;
+}
+.doc-label { border-radius: 15px; padding: 0 5px; }
+.doc-label code { background-color: transparent; color: white;}
+.doc-label-special { background-color: blue; color: white; }
+.doc-label-private { background-color: red; color: white; }
+.doc-label-property { background-color: green; color: white; }
+.doc-label-read-only { background-color: yellow; color: black; }
diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png
diff --git a/docs/development.md b/docs/development.md
@@ -0,0 +1,58 @@
+---
+title: Development 
+summary: How to develop psmq. 
+date: 2023-08-27
+---
+
+# Installing from source for development
+
+Clone the repo:
+
+```shell
+$ git clone https://github.com/callowayproject/psmq
+```
+
+`Poetry` is required. Optionally set a local python version with `pyenv`.
+
+```shell
+$ pipx install poetry
+$ poetry install --with dev,test,docs
+$ poetry env info
+```
+
+If you hit errors like `Poetry: Failed to unlock the collection` add `export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring` to your `.bashrc` / `.zshrc` and source it.
+
+Run Python Simple Message Queue's tests from the source tree on your machine:
+
+```shell
+$ poetry run pytest
+```
+
+## Development Flow
+
+This project uses the [GitHubFlow](https://docs.github.com/en/get-started/quickstart/github-flow) workflow.
+
+Rationale:
+
+* The primary branch is always releasable.
+* Lightweight.
+* Single long-lived branch. Less maintenance overhead, faster iterations.
+* Simple for one person projects, as well as collaboration.
+
+Put simply:
+
+1. Anything in the primary branch is deployable
+2. To work on something new, create a descriptively named branch off the primary branch (ie: new-oauth2-scopes)
+3. Commit to that branch locally and regularly push your work to the same named branch on GitHub
+4. When you need feedback or help, or you think the branch is ready for merging, open a pull request
+5. After someone else has reviewed and signed off on the feature, you can merge it into the primary branch
+6. Once it is merged and pushed to the primary branch, you can and should deploy immediately
+
+**Merging**
+
+Merges are done via Pull Requests. 
+
+
+**Tags**
+
+Tags are used to denote releases.
diff --git a/docs/explanation.md b/docs/explanation.md
@@ -0,0 +1,20 @@
+---
+title: Explanations
+summary: Why Python Simple Message Queue is the way it is!
+date: 2023-08-27
+---
+
+This page explains why Python Simple Message Queue is the way it is.
+
+!!! warning
+
+   Explanation has not been implemented yet!
+
+Explanation is **discussion** that clarifies and illuminates a particular topic. Explanation is **understanding-oriented.**
+
+- Give context and background on your library
+- Explain why you created it
+- Provide multiple examples and approaches of how to work with it
+- Help the reader make connections
+- Avoid writing instructions or technical descriptions here
+- [More Information](https://diataxis.fr/explanation/)
diff --git a/docs/gen_doc_stubs.py b/docs/gen_doc_stubs.py
@@ -0,0 +1,35 @@
+"""Generate documentation stubs."""
+from pathlib import Path
+from typing import Set
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+src_root = Path("psmq")
+exclude: Set[str] = set()
+
+for path in sorted(src_root.rglob("*.py")):
+    module_path = path.with_suffix("")
+    doc_path = path.with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1].startswith("_"):
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())
diff --git a/docs/glossary.md b/docs/glossary.md
@@ -0,0 +1,11 @@
+---
+title: Glossary 
+summary: A glossary of terminology used in the Python Simple Message Queue package and documentation. 
+date: 2023-08-27
+---
+
+A glossary of terminology and nomenclature used in the psmq package and documentation.
+
+!!! warning
+
+    Glossary not implemented yet! Recommend each item has its own anchor link.
diff --git a/docs/howtos/index.md b/docs/howtos/index.md
@@ -0,0 +1,15 @@
+---
+title: How Tos 
+summary: Recipes for common tasks using Python Simple Message Queue.
+date: 2023-08-27
+---
+
+The *How To's* are intended as recipes for common tasks using psmq. See the API reference for detailed reference documentation and function, class etc definitions. 
+
+!!! warning
+
+    How Tos not implemented yet!
+
+How-to guides are directions that take the reader through the steps required to solve a real-world problem. How-to guides are **goal-oriented.**
+
+[More information](https://diataxis.fr/how-to-guides/)
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,15 @@
+---
+title: psmq
+summary: Python Simple Message Queue
+date: 2023-08-27
+---
+
+# Python Simple Message Queue
+
+> *Python Simple Message Queue*
+
+## What Next
+
+To get going quickly head over to the [Quick Start](quickstart.md) tutorial, then check out the [Tutorials](tutorials/index.md), [Reference](reference/index.md), or [How-tos](howtos/index.md) for more information. Developers should check out the [Developer Guide](development.md) for even more detailed information and advice on how to extend psmq.
+
+The [Glossary](glossary.md) lists terms and nomenclature used in the package and in this documentation.
diff --git a/docs/installation.md b/docs/installation.md
@@ -0,0 +1,20 @@
+---
+title: Installation 
+summary: How to install psmq. 
+date: 2023-08-27
+---
+
+!!! warning
+
+    Installation instructions not implemented yet!
+
+
+## Installing the Stable Release from PyPI
+
+To install psmq, run this command in your terminal:
+
+``` console
+$ pip install psmq
+```
+
+This is the preferred method to install psmq, as it will always install the most recent stable release. You can also replace `pip` with `pipx`.
diff --git a/docs/model.md b/docs/model.md
@@ -0,0 +1,30 @@
+Python Simple Message Queue (psmq) Model
+
+- QueueManager
+  - main entry point for developers
+  - creates and manages a Connection object
+  - sets up queues and their configuration with appropriate serializers and deserializers
+- Connection
+  - manages connection to the broker
+  - provides low-level communication with the broker
+- Queue
+  - high-level interface for sending and receiving messages including automatic serialization and deserialization 
+- ReceivedMessage
+  - represents a message received from a queue
+  - provides access to the message's data and metadata
+- Serializer
+  - a callable that takes a Python object and returns a byte string 
+- Deserializer
+  - a callable that takes a byte string and returns a Python object 
+- psmq_library.lua
+  - The Lua library that is loaded by the broker and does the actual work of queue management
+
+Streams:
+
+Producer (client ID, topic/channel, server)
+    - produce
+    - flush or poll for acks?
+
+Consumer (group ID, auto-commit, server)
+    - consume
+    - commit
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -0,0 +1,31 @@
+---
+title: Quickstart 
+summary: Quickstart instructions for Python Simple Message Queue.
+date: 2023-08-27
+---
+
+Getting started quickly with Python Simple Message Queue.
+
+!!! warning
+
+    Quickstart instructions not implemented yet!
+
+## Prerequisites
+
+## Installation
+
+From source...from pypi?
+
+## The Basics
+To use `psmq` in a project:
+
+```python
+import psmq
+```
+
+
+## Basic Operations
+
+## Tips and Tricks
+
+## Further Reading
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -0,0 +1,15 @@
+---
+title: Reference 
+summary: Technical reference of Python Simple Message Queue.
+date: 2023-08-27
+---
+
+The *Reference* is intended as technical descriptions of the parts of psmq.
+
+!!! warning
+
+    Reference not implemented yet!
+
+Reference guides are technical descriptions of the machinery and how to operate it. Reference material is **information-oriented.**
+
+[More information](https://diataxis.fr/reference/)
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
@@ -0,0 +1,22 @@
+---
+title: Tutorials 
+summary: Tutorials for how to use Python Simple Message Queue.
+date: 2023-08-27
+---
+
+This page provides tutorials on how to use psmq.
+
+!!! warning
+
+    Tutorials not implemented yet! Tutorials are for learning how to use the package.
+
+Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. Tutorials are **learning-oriented.**
+
+- Help newcomers with getting started
+- Teach readers about your library by making them write code
+- Inspire confidence through examples that work for everyone, repeatably
+- Give readers an immediate sense of achievement
+- Show concrete examples, no abstractions
+- Provide the minimum necessary explanation
+- Avoid any distractions
+- [More information](https://diataxis.fr/tutorials/)
