diff --git a/docs/assets/chr_logo.png b/docs/assets/chr_logo.png new file mode 100644 index 0000000..1bda8b1 Binary files /dev/null and b/docs/assets/chr_logo.png differ diff --git a/docs/assets/extra.css b/docs/assets/extra.css new file mode 100644 index 0000000..51a8e5b --- /dev/null +++ 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,'); + 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 new file mode 100644 index 0000000..df16a6f Binary files /dev/null and b/docs/assets/favicon.png differ diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..ba8aa29 --- /dev/null +++ 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 new file mode 100644 index 0000000..a843b72 --- /dev/null +++ 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 new file mode 100644 index 0000000..2e7b244 --- /dev/null +++ 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 new file mode 100644 index 0000000..2d38d69 --- /dev/null +++ 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 new file mode 100644 index 0000000..43be031 --- /dev/null +++ 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 new file mode 100644 index 0000000..620097c --- /dev/null +++ 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 new file mode 100644 index 0000000..331954b --- /dev/null +++ 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 new file mode 100644 index 0000000..b643fdf --- /dev/null +++ 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 new file mode 100644 index 0000000..c1b267a --- /dev/null +++ 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 new file mode 100644 index 0000000..5508a38 --- /dev/null +++ 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 new file mode 100644 index 0000000..04d9878 --- /dev/null +++ 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/)