feat: Add ptcolors source code (#3) (#4)

* feat: Add bash aliases and functions for easier navigation and environment setup

* chore: Add GitHub workflows for continuous deployment, testing, documentation, and linting

* chore: Add Sphinx documentation build system

* chore: Add environment configuration files for development, production, staging, and testing

* chore: Add sleeping daemon script and CI script

* chore: Add requirements files for development, production, staging, and testing

* feat: added tcolors source code

* WIP

* chore: Fix indentation issue in tcolors.py

* chore: Update sys.path in conf.py to fix import issue

* chore: Update license

* chore: Update README

* chore: Add VERSION file with initial version number

* chore: Added test_tcolors.py

* chore: Fix missing newline at end of file in run-ci.sh

* chore: Add Dockerfile and docker-compose.yml for containerization

* chore: Update sys.path in conf.py to fix import issue

* chore: Update build_docs Makefile and conf.py

* chore: Remove unnecessary files and configurations

* chore: Update super-linter workflow configuration

* chore: Remove unused files

* chore: Remove build_docs Makefile and make.bat

* chore: Update build_docs Makefile and conf.py

* chore: Update build_docs Makefile and conf.py

* chore: Update runs-on value in docs.yml workflow

* chore: Update Sphinx documentation workflow and dependencies

* chore: Update Sphinx documentation workflow and dependencies

* chore: Update Sphinx documentation workflow and dependencies

* chore: Refactor setup.py to improve package installation process

* Refactor setup.py to improve package installation process

* chore: Update package name in setup.py to ptcolors

* chore: Update package name to ptcolors and refactor setup.py for improved package installation process

* Refactor package structure and update imports for ptcolors

* Refactor ptcolors import in README.md

* chore: Update package name to ptcolors and refactor setup.py for improved package installation process

* chore: Update package version to 0.1.2 in setup.py

* chore: Update package version to 0.1.3 in setup.py

* chore: Add environment files for development, production, staging, and testing

* chore: Remove environment files for development, production, staging, and testing

* Update LICENSE



* chore: Update .gitignore to include blank line

* chore: Update Sphinx documentation workflow

* chore: Refactor GitHub Actions workflow for branch-check job in guard.yml

---------

Co-authored-by: Cheikh Mbengue <97647866+cmbengue-ec-intl@users.noreply.github.com>

.github/workflows/docs.yml

@@ -0,0 +1,77 @@
+name: Sphinx-docs
+
+on:
+  pull_request:
+    types:
+      - auto_merge_enabled
+    branches:
+      - staging
+  merge_group:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  checks: read
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Preamble
+        run: |
+          echo "🎉 A ${{ github.event_name }} triggered a ${{ runner.os }} job."
+          echo "🔎 The branch is ${{ github.ref_name }} in ${{ github.repository }}."
+        
+      - name: Check out repository code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install Python dependencies
+        run: |
+          echo "📦 Installing Python dependencies."
+          python -m pip install --upgrade pip
+          if [ -f requirements/testing.txt ]; then
+            pip install -r requirements/testing.txt;
+          fi
+
+      - name: Run Sphinx
+        run: |
+          echo "📦 Running Sphinx."
+          python -m venv pyenv
+          source pyenv/bin/activate
+          cd build_docs
+          sphinx-build -b html src ../docs
+
+      - name: Deploy to GitHub Pages
+        if: github.ref == 'refs/heads/main'
+        run: |
+          mkdir -p /tmp/"${{ github.repository }}"-d
+          cp -r docs/* /tmp/"${{ github.repository }}"-d/
+          git config user.name "${{ github.actor }}"
+          git config user.email "${{ github.actor }}@users.noreply.github.com"
+          git fetch
+          git checkout -B gh-pages origin/gh-pages || git checkout --orphan gh-pages
+          rm -rf ./*
+          cp -r /tmp/"${{ github.repository }}"-d/* .
+          touch .nojekyll
+          git add .
+          git commit -m "🚀 $(date): update docs"
+          git push origin gh-pages --force
+
+      - name: Cleanup deployment
+        if: github.ref == 'refs/heads/main'
+        run: |
+          echo "Cleaning up now."
+          rm -rf /tmp/"${{ github.repository }}"-d/
+
+      - name: Finish
+        run: |
+          echo "📣 The job has been completed."
+          echo "🍏 This job's status is ${{ job.status }}."

.github/workflows/guard.yml

@@ -0,0 +1,34 @@
+---
+    name: Guard Main Branch
+    on:
+      pull_request:
+        types:
+          - auto_merge_enabled
+        branches:
+          - main
+      merge_group:
+    permissions:
+      contents: read
+    jobs:
+      branch-check:
+        runs-on: ubuntu-latest
+        if: ${{ !contains(github.event.head_commit.message, '[skip ci]') && !contains(github.event.head_commit.message, '[ci skip]') }}
+        steps:
+          - name: Preamble
+            run: |
+              echo "🎉 A $EVENT triggered a ${{ runner.os }} job."
+              echo "🔎 The branch is $BRANCH in $REPO."
+          - name: Check out repository code
+            uses: actions/checkout@v4
+          - name: Guard the main branch
+            if: ${{ env.HEAD != 'staging' && env.HEAD != ''}}
+            run: |
+              echo "🚫 The main branch is protected."
+              echo "🚫 Pull requests to main must come from staging branch."
+              exit 1
+          - name: Notify
+            run: |
+              echo "📣 The job has been completed."
+              echo "🔔 The main branch is protected."
+              echo "🍏 This job's status is ${{ job.status }}."
+

.github/workflows/super-linter.yml

@@ -0,0 +1,38 @@
+# This workflow executes several linters on changed
+# files based on languages used in your code base whenever
+# you push a code or open a pull request.
+#
+# You can adjust the behavior by modifying this file.
+# For more information, see:
+# https://github.com/github/super-linter
+---
+  name: Lint Codebase
+
+  on:
+    pull_request:
+      types: [auto_merge_enabled]
+      branches: [staging]
+    merge_group:
+
+  jobs:
+    run-lint:
+      runs-on: ubuntu-latest
+      steps:
+        - name: Checkout code
+          uses: actions/checkout@v4
+          with:
+            # Full git history is needed to get a proper
+            # list of changed files within `super-linter`
+            fetch-depth: 0
+
+        - name: Lint Code Base
+          uses: github/super-linter@v5
+          env:
+            VALIDATE_ALL_CODEBASE: true
+            DEFAULT_BRANCH: main
+            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+            VALIDATE_DOCKERFILE_HADOLINT: false
+            VALIDATE_JSCPD: false
+            VALIDATE_GITHUB_ACTIONS: false
+            VALIDATE_HTML: false
+            VALIDATE_PYTHON_BLACK: false

.gitignore

@@ -160,3 +160,6 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# Mac file system caches and hidden files
+.DS_Store

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright [2020 - 2024] [Elizabth Consulting International Inc.]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -0,0 +1,97 @@
+# ptcolors Repository
+
+`ptcolors` is a lightweight Python package designed to add vibrant, customizable colors to your terminal output with minimal effort. Whether you’re building command-line applications, scripts, or simply want to enhance the readability of your terminal messages, `ptcolors` provides an easy-to-use interface to bring your text to life.
+
+With `ptcolors`, you can apply a wide range of colors and styles to your terminal text, making it more engaging and visually appealing. It's perfect for developers who want to add a splash of color to their terminal without dealing with the complexities of ANSI escape codes.
+
+## Project Status
+
+Here's the current status of our workflows:
+
+| Workflow                | Status |
+|-------------------------|--------|
+| Documentation           | ![Docs](https://img.shields.io/badge/Docs-passing-brightgreen) |
+| Guard Main Branch       | ![Guard Main Branch](https://img.shields.io/badge/Guard%20Main%20Branch-passing-brightgreen) |
+| Code Quality Checker           | ![Lint Code Base](https://img.shields.io/badge/Lint%20Code%20Base-passing-brightgreen) |
+
+## Components
+
+The ptcolors's codebase structure is as shown below:
+
+```plaintext
+.
+├── LICENSE
+├── README.md
+├── VERSION
+├── build_docs
+│   ├── Makefile
+│   ├── __init__.py
+│   ├── build
+│   ├── make.bat
+│   └── src
+│       ├── __init__.py
+│       ├── _static
+│       ├── _templates
+│       ├── conf.py
+│       ├── index.rst
+│       └── ptcolors.rst
+├── requirements
+│   ├── testing.txt
+├── requirements.txt
+├── setup.py
+└── src
+    ├── ptcolors
+    │   ├── __init__.py
+    │   └── ptcolors.py
+    └── tests
+        ├── __init__.py
+        └── test_ptcolors.py
+
+```
+
+## Example
+
+Here's an example of how to use `ptcolors`:
+
+```python
+from ptcolors.ptcolors import TColors
+
+ptcolors = ptcolors()
+ptcolors.headermsg("This is a header message.")
+ptcolors.okmsg("This is a success message.")
+ptcolors.warnmsg("This is a warning message.")
+ptcolors.failmsg("This is a failure message.")
+ptcolors.infomsg("This is an info message.")
+```
+
+This should create a terminal output similar to the one below.
+
+<pre style="color: lightgreen; background-color: black;">
+2024-08-21 10:33:39 [ <span style="color: magenta;">NOTICE</span> ] This is a header message.
+2024-08-21 10:33:39 [ <span style="color: green;">SUCCESS</span> ] This is a success message.
+2024-08-21 10:33:39 [ <span style="color: yellow;">WARNING</span> ] This is a warning message.
+2024-08-21 10:33:39 [ <span style="color: red;">FAILURE</span> ] This is a failure message.
+2024-08-21 10:33:39 [ <span style="color: blue;">INFORMATION</span> ] This is an info message.
+</pre>
+
+Here’s an example of using a context manager to handle resources, like managing messages during a function’s execution. Context managers in Python, typically implemented with the with statement, allow you to control resource allocation and release efficiently.
+
+```python
+from ptcolors.ptcolors import TColors
+
+msg = TColors()
+
+def __call__(self):
+    """Run the target sequence."""
+    # The context manager is entered here, and the messages are set up.
+    with self.msg.messages(
+        f"Starting {self.name()}...",  # Message displayed at the start
+        f"{self.name()} complete.",    # Message displayed on successful completion
+        f"{self.name()} failed.",      # Message displayed on failure
+        self.config["function"],       # The function to be executed
+        *self.config["function-arguments"],  # Positional arguments for the function
+        **self.config,                 # Keyword arguments for the function
+    ) as status:
+        # The status is set based on the outcome of the context manager block
+        self.status = status
+```

VERSION

@@ -0,0 +1 @@
+0.1.3

build_docs/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     = src
+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)

build_docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

build_docs/src/conf.py

@@ -0,0 +1,58 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../../src/ptcolors"))
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath("."))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "ptcolors"
+copyright = "2024, Elizabeth Consulting International Inc."
+author = "Elizabeth Consulting International Inc."
+
+# The full version, including alpha/beta/rc tags
+release = "0.1.0"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
+# ones.
+extensions = ["sphinx.ext.autodoc"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns: list[str] = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "cloud"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]