Add sphinx documentation and update README.md

Add a new GH workflow for markdown validation

.github/workflows/markdown.yaml

@@ -0,0 +1,15 @@
+name: none-shall-pass
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '**/*.md'
+  workflow_dispatch:
+
+jobs:
+  none-shall-pass:
+    runs-on: thevickypedia-lite
+    steps:
+      - uses: thevickypedia/none-shall-pass@v5

.gitignore

@@ -7,4 +7,6 @@ __pycache__/
 build/
 PyNinja.egg-info/
 
+doc_gen/_*
+
 temp.py

.pre-commit-config.yaml

@@ -43,3 +43,12 @@ repos:
     hooks:
       - id: isort
         args: [ --profile, black ]
+
+  - repo: local
+    hooks:
+      - id: docs
+        name: runbook
+        entry: /bin/bash pre_commit.sh
+        language: system
+        pass_filenames: false
+        always_run: true

README.md

@@ -1,2 +1,134 @@
 # PyNinja
 Light weight OS agnostic service monitoring API
+
+![Python][label-pyversion]
+
+**Platform Supported**
+
+![Platform][label-platform]
+
+**Deployments**
+
+[![pages][label-actions-pages]][gha_pages]
+[![pypi][label-actions-pypi]][gha_pypi]
+[![markdown][label-actions-markdown]][gha_md_valid]
+
+[![Pypi][label-pypi]][pypi]
+[![Pypi-format][label-pypi-format]][pypi-files]
+[![Pypi-status][label-pypi-status]][pypi]
+
+## Kick off
+
+**Recommendations**
+
+- Install `python` [3.10] or [3.11]
+- Use a dedicated [virtual environment]
+
+**Install PyNinja**
+```shell
+python -m pip install pyninja
+```
+
+**Initiate - IDE**
+```python
+import pyninja
+
+
+if __name__ == '__main__':
+    pyninja.start()
+```
+
+**Initiate - CLI**
+```shell
+pyninja start
+```
+
+> Use `pyninja --help` for usage instructions.
+
+## Environment Variables
+
+<details>
+<summary><strong>Sourcing environment variables from an env file</strong></summary>
+
+> _By default, `PyNinja` will look for a `.env` file in the current working directory._
+</details>
+
+- **NINJA_HOST** - Hostname for the API server.
+- **NINJA_PORT** - Port number for the API server.
+- **WORKERS** - Number of workers for the uvicorn server.
+- **APIKEY** - API Key for authentication.
+
+## Coding Standards
+Docstring format: [`Google`][google-docs] <br>
+Styling conventions: [`PEP 8`][pep8] and [`isort`][isort]
+
+## [Release Notes][release-notes]
+**Requirement**
+```shell
+python -m pip install gitverse
+```
+
+**Usage**
+```shell
+gitverse-release reverse -f release_notes.rst -t 'Release Notes'
+```
+
+## Linting
+`pre-commit` will ensure linting, run pytest, generate runbook & release notes, and validate hyperlinks in ALL
+markdown files (including Wiki pages)
+
+**Requirement**
+```shell
+python -m pip install sphinx==5.1.1 pre-commit recommonmark
+```
+
+**Usage**
+```shell
+pre-commit run --all-files
+```
+
+## Pypi Package
+[![pypi-module][label-pypi-package]][pypi-repo]
+
+[https://pypi.org/project/PyNinja/][pypi]
+
+## Runbook
+[![made-with-sphinx-doc][label-sphinx-doc]][sphinx]
+
+[https://thevickypedia.github.io/PyNinja/][runbook]
+
+## License & copyright
+
+&copy; Vignesh Rao
+
+Licensed under the [MIT License][license]
+
+[//]: # (Labels)
+
+[label-actions-markdown]: https://github.com/thevickypedia/PyNinja/actions/workflows/markdown.yaml/badge.svg
+[label-pypi-package]: https://img.shields.io/badge/Pypi%20Package-pyninja-blue?style=for-the-badge&logo=Python
+[label-sphinx-doc]: https://img.shields.io/badge/Made%20with-Sphinx-blue?style=for-the-badge&logo=Sphinx
+[label-pyversion]: https://img.shields.io/badge/python-3.10%20%7C%203.11-blue
+[label-platform]: https://img.shields.io/badge/Platform-Linux|macOS|Windows-1f425f.svg
+[label-actions-pages]: https://github.com/thevickypedia/PyNinja/actions/workflows/pages/pages-build-deployment/badge.svg
+[label-actions-pypi]: https://github.com/thevickypedia/PyNinja/actions/workflows/python-publish.yaml/badge.svg
+[label-pypi]: https://img.shields.io/pypi/v/PyNinja
+[label-pypi-format]: https://img.shields.io/pypi/format/PyNinja
+[label-pypi-status]: https://img.shields.io/pypi/status/PyNinja
+
+[3.10]: https://docs.python.org/3/whatsnew/3.10.html
+[3.11]: https://docs.python.org/3/whatsnew/3.11.html
+[virtual environment]: https://docs.python.org/3/tutorial/venv.html
+[release-notes]: https://github.com/thevickypedia/PyNinja/blob/master/release_notes.rst
+[gha_pages]: https://github.com/thevickypedia/PyNinja/actions/workflows/pages/pages-build-deployment
+[gha_pypi]: https://github.com/thevickypedia/PyNinja/actions/workflows/python-publish.yaml
+[gha_md_valid]: https://github.com/thevickypedia/PyNinja/actions/workflows/markdown.yaml
+[google-docs]: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
+[pep8]: https://www.python.org/dev/peps/pep-0008/
+[isort]: https://pycqa.github.io/isort/
+[sphinx]: https://www.sphinx-doc.org/en/master/man/sphinx-autogen.html
+[pypi]: https://pypi.org/project/PyNinja
+[pypi-files]: https://pypi.org/project/PyNinja/#files
+[pypi-repo]: https://packaging.python.org/tutorials/packaging-projects/
+[license]: https://github.com/thevickypedia/PyNinja/blob/master/LICENSE
+[runbook]: https://thevickypedia.github.io/PyNinja/

doc_gen/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc_gen/README.md

@@ -0,0 +1,134 @@
+# PyNinja
+Light weight OS agnostic service monitoring API
+
+![Python][label-pyversion]
+
+**Platform Supported**
+
+![Platform][label-platform]
+
+**Deployments**
+
+[![pages][label-actions-pages]][gha_pages]
+[![pypi][label-actions-pypi]][gha_pypi]
+[![markdown][label-actions-markdown]][gha_md_valid]
+
+[![Pypi][label-pypi]][pypi]
+[![Pypi-format][label-pypi-format]][pypi-files]
+[![Pypi-status][label-pypi-status]][pypi]
+
+## Kick off
+
+**Recommendations**
+
+- Install `python` [3.10] or [3.11]
+- Use a dedicated [virtual environment]
+
+**Install PyNinja**
+```shell
+python -m pip install pyninja
+```
+
+**Initiate - IDE**
+```python
+import pyninja
+
+
+if __name__ == '__main__':
+    pyninja.start()
+```
+
+**Initiate - CLI**
+```shell
+pyninja start
+```
+
+> Use `pyninja --help` for usage instructions.
+
+## Environment Variables
+
+<details>
+<summary><strong>Sourcing environment variables from an env file</strong></summary>
+
+> _By default, `PyNinja` will look for a `.env` file in the current working directory._
+</details>
+
+- **NINJA_HOST** - Hostname for the API server.
+- **NINJA_PORT** - Port number for the API server.
+- **WORKERS** - Number of workers for the uvicorn server.
+- **APIKEY** - API Key for authentication.
+
+## Coding Standards
+Docstring format: [`Google`][google-docs] <br>
+Styling conventions: [`PEP 8`][pep8] and [`isort`][isort]
+
+## [Release Notes][release-notes]
+**Requirement**
+```shell
+python -m pip install gitverse
+```
+
+**Usage**
+```shell
+gitverse-release reverse -f release_notes.rst -t 'Release Notes'
+```
+
+## Linting
+`pre-commit` will ensure linting, run pytest, generate runbook & release notes, and validate hyperlinks in ALL
+markdown files (including Wiki pages)
+
+**Requirement**
+```shell
+python -m pip install sphinx==5.1.1 pre-commit recommonmark
+```
+
+**Usage**
+```shell
+pre-commit run --all-files
+```
+
+## Pypi Package
+[![pypi-module][label-pypi-package]][pypi-repo]
+
+[https://pypi.org/project/PyNinja/][pypi]
+
+## Runbook
+[![made-with-sphinx-doc][label-sphinx-doc]][sphinx]
+
+[https://thevickypedia.github.io/PyNinja/][runbook]
+
+## License & copyright
+
+&copy; Vignesh Rao
+
+Licensed under the [MIT License][license]
+
+[//]: # (Labels)
+
+[label-actions-markdown]: https://github.com/thevickypedia/PyNinja/actions/workflows/markdown.yaml/badge.svg
+[label-pypi-package]: https://img.shields.io/badge/Pypi%20Package-pyninja-blue?style=for-the-badge&logo=Python
+[label-sphinx-doc]: https://img.shields.io/badge/Made%20with-Sphinx-blue?style=for-the-badge&logo=Sphinx
+[label-pyversion]: https://img.shields.io/badge/python-3.10%20%7C%203.11-blue
+[label-platform]: https://img.shields.io/badge/Platform-Linux|macOS|Windows-1f425f.svg
+[label-actions-pages]: https://github.com/thevickypedia/PyNinja/actions/workflows/pages/pages-build-deployment/badge.svg
+[label-actions-pypi]: https://github.com/thevickypedia/PyNinja/actions/workflows/python-publish.yaml/badge.svg
+[label-pypi]: https://img.shields.io/pypi/v/PyNinja
+[label-pypi-format]: https://img.shields.io/pypi/format/PyNinja
+[label-pypi-status]: https://img.shields.io/pypi/status/PyNinja
+
+[3.10]: https://docs.python.org/3/whatsnew/3.10.html
+[3.11]: https://docs.python.org/3/whatsnew/3.11.html
+[virtual environment]: https://docs.python.org/3/tutorial/venv.html
+[release-notes]: https://github.com/thevickypedia/PyNinja/blob/master/release_notes.rst
+[gha_pages]: https://github.com/thevickypedia/PyNinja/actions/workflows/pages/pages-build-deployment
+[gha_pypi]: https://github.com/thevickypedia/PyNinja/actions/workflows/python-publish.yaml
+[gha_md_valid]: https://github.com/thevickypedia/PyNinja/actions/workflows/markdown.yaml
+[google-docs]: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
+[pep8]: https://www.python.org/dev/peps/pep-0008/
+[isort]: https://pycqa.github.io/isort/
+[sphinx]: https://www.sphinx-doc.org/en/master/man/sphinx-autogen.html
+[pypi]: https://pypi.org/project/PyNinja
+[pypi-files]: https://pypi.org/project/PyNinja/#files
+[pypi-repo]: https://packaging.python.org/tutorials/packaging-projects/
+[license]: https://github.com/thevickypedia/PyNinja/blob/master/LICENSE
+[runbook]: https://thevickypedia.github.io/PyNinja/

doc_gen/conf.py

@@ -0,0 +1,27 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'PyNinja'
+copyright = '2024, Vignesh Rao'
+author = 'Vignesh Rao'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']