From b5afefd793c976cc38e975793b8ada2627be259e Mon Sep 17 00:00:00 2001 From: Crispen Gari Date: Tue, 9 Apr 2024 16:58:19 +0200 Subject: [PATCH] read the docs doc --- .readthedocs.yaml | 31 ++++ Changelog.md | 10 +- README.md | 2 +- docs/Makefile | 20 +++ docs/make.bat | 35 +++++ docs/requirements.txt | 4 + docs/source/_static/css/index.css | 3 + docs/source/conf.py | 57 +++++++ docs/source/features.rst | 11 ++ docs/source/github/contribution.rst | 5 + docs/source/github/license.rst | 4 + docs/source/index.rst | 47 ++++++ docs/source/installation.rst | 16 ++ docs/source/usage.rst | 224 ++++++++++++++++++++++++++++ pyproject.toml | 2 +- 15 files changed, 468 insertions(+), 3 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/requirements.txt create mode 100644 docs/source/_static/css/index.css create mode 100644 docs/source/conf.py create mode 100644 docs/source/features.rst create mode 100644 docs/source/github/contribution.rst create mode 100644 docs/source/github/license.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/installation.rst create mode 100644 docs/source/usage.rst diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..42e103b --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,31 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + # You can also specify other tool versions: + # nodejs: "19" + # rust: "1.64" + # golang: "1.19" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/source/conf.py +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: docs/requirements.txt diff --git a/Changelog.md b/Changelog.md index 184691a..e900aa9 100644 --- a/Changelog.md +++ b/Changelog.md @@ -1,9 +1,17 @@ === -tabulato **`1.0.3`** +tabulato **`1.0.4`** === ### Release Notes - `tabulato` +We have release the new `tabulato` Version `1.0.4` (`2024-04-09`) + +##### Changes + +- Updated documentation. + +### Release Notes - `tabulato` + We have release the new `tabulato` Version `1.0.3` (`2024-03-07`) ##### Changes diff --git a/README.md b/README.md index d1b7733..2cf2d60 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ With `tabulato`, you can easily format your data into tables with specified head - Option to make headers bold for emphasis. - User-friendly API for straightforward integration into your Python projects. -> tabulato simplifies the task of formatting and presenting tabular data in terminal environments, making it an essential tool for developers and data scientists working with command-line interfaces. +> `tabulato` simplifies the task of formatting and presenting tabular data in terminal environments, making it an essential tool for developers and data scientists working with command-line interfaces. ### Installation diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/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 = source +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) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..dc1312a --- /dev/null +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..1ee13a2 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +# Defining the exact version will make sure things don't break +sphinx==5.3.0 +sphinx_rtd_theme==1.1.1 +readthedocs-sphinx-search==0.1.1 \ No newline at end of file diff --git a/docs/source/_static/css/index.css b/docs/source/_static/css/index.css new file mode 100644 index 0000000..4918389 --- /dev/null +++ b/docs/source/_static/css/index.css @@ -0,0 +1,3 @@ +table.my-table td { + white-space: normal !important; +} diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..3adea49 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,57 @@ +# 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 = "tabulato" +copyright = "2024, Crispen Gari" +author = "Crispen Gari" + + +# -- 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 = [] + +# 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 = [] + + +# -- 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 = "sphinx_rtd_theme" +highlight_language = "python" + +# 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"] + + +html_css_files = [ + "css/index.css", +] diff --git a/docs/source/features.rst b/docs/source/features.rst new file mode 100644 index 0000000..3f80538 --- /dev/null +++ b/docs/source/features.rst @@ -0,0 +1,11 @@ +Features +++++++++ + +**Key features of tabulato include** + +- Generating tables with customizable colors for headers, even rows, and odd rows. +- Specifying required columns to ensure important data is always displayed. +- Option to make headers bold for emphasis. +- User-friendly API for straightforward integration into your Python projects. + +> ``tabulato`` simplifies the task of formatting and presenting tabular data in terminal environments, making it an essential tool for developers and data scientists working with command-line interfaces. diff --git a/docs/source/github/contribution.rst b/docs/source/github/contribution.rst new file mode 100644 index 0000000..658147a --- /dev/null +++ b/docs/source/github/contribution.rst @@ -0,0 +1,5 @@ + +Contributing +++++++++++++ + +To contribute to ``tabulato`` open a pull request on `GitHub `_ file. \ No newline at end of file diff --git a/docs/source/github/license.rst b/docs/source/github/license.rst new file mode 100644 index 0000000..1bffbe4 --- /dev/null +++ b/docs/source/github/license.rst @@ -0,0 +1,4 @@ +License ++++++++ + +This project is licensed under the ``MIT`` License - see the `LICENSE `_ file for details. diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..0a0dae4 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,47 @@ +.. tabulato documentation master file, created by + sphinx-quickstart on Tue Apr 9 07:38:42 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to ``tabulato's`` documentation! +======================================== + +``tabulato`` is a Python package that provides functionality for generating tabulated representations of data with customizable colors and formatting options. It offers a user-friendly interface for creating visually appealing tables in terminal output. + +With ``tabulato``, you can easily format your data into tables with specified headers, apply different colors to headers and rows, and customize the appearance of your tabulated data. Whether you're working on command-line applications, data analysis scripts, or any other project that requires presenting data in a tabular format, ``tabulato`` can help streamline the process and enhance the visual presentation of your data. + +.. raw:: html + +

+ + + + +

+ +**What's missing on this package?** + +This package lacks ``wrapping`` of text for long lines. This ``version`` only support small tables. Long column data might not end up displayed well, however with small column data like this package is the best. + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Getting Started + + installation + usage + features + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: GitHub and Contribution + + github/contribution + github/license + + + + + + diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..e6d6fd9 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,16 @@ + +Installation +++++++++++++ + +To install ``tabulato``, you can use pip: + +.. code-block:: shell + + pip install tabulato + +**Python Version** + +This package support python version ``>=3.10`` + + +Once you install ``tabulato`` now you are ready to use it in your projects. \ No newline at end of file diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 0000000..5cccf35 --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,224 @@ +Usage ++++++ + +In the following examples shows you how you can use + +.. code-block:: python + + from tabulato import colorful_tabulate, TableRowStyle + + headers = ["Name", "Student Number", "DOB", "Email Address"] + + data = [ + ["John Doe", "S12345", "1995-07-15", "john@example.com"], + ["Alice Smith", "S67890", "1998-03-22", "alice@example.com"], + ["Bob Johnson", "S54321", "1997-11-10", "bob@example.com"], + ["Emma Brown", "S98765", "1996-09-18", "emma@example.com"], + ["Michael Lee", "S24680", "1999-05-30", "michael@example.com"], + ["Sophia Wang", "S13579", "1994-12-05", "sophia@example.com"], + ["David Chen", "S75310", "1992-04-08", "david@example.com"], + ["Olivia Kim", "S36924", "1993-10-25", "olivia@example.com"], + ] + + colorful_tabulate( + data=data, + column_widths=[20, 20, 20, 30], + ) + + +.. note:: The above function will result in the following table being created in the terminal. + +.. rst-class:: my-table + ++----------------------+----------------------+----------------------+--------------------------------+ +| name | student number | dob | email | ++======================+======================+======================+================================+ +| John Doe | S12345 | 1995-07-15 | john@example.com | ++----------------------+----------------------+----------------------+--------------------------------+ +| Alice Smith | S67890 | 1998-03-22 | alice@example.com | ++----------------------+----------------------+----------------------+--------------------------------+ +| Bob Johnson | S54321 | 1997-11-10 | bob@example.com | ++----------------------+----------------------+----------------------+--------------------------------+ +| Emma Brown | S98765 | 1996-09-18 | emma@example.com | ++----------------------+----------------------+----------------------+--------------------------------+ +| Michael Lee | S24680 | 1999-05-30 | michael@example.com | ++----------------------+----------------------+----------------------+--------------------------------+ +| Sophia Wang | S13579 | 1994-12-05 | sophia@example.com | ++----------------------+----------------------+----------------------+--------------------------------+ +| David Chen | S75310 | 1992-04-08 | david@example.com | ++----------------------+----------------------+----------------------+--------------------------------+ +| Olivia Kim | S36924 | 1993-10-25 | olivia@example.com | ++----------------------+----------------------+----------------------+--------------------------------+ + + + +The colorful table will look as follows: + +.. image:: https://github.com/CrispenGari/tabulato/blob/main/images/0.jpg?raw=true + :align: center + :width: 400 + + +However you can style the rows of the table using the ``TableRowStyle`` class by specifying the options as follows: + +.. code-block:: python + + colorful_tabulate( + data=data, + column_widths=[20, 20, 20, 30], + header_style=TableRowStyle( + bold=True, + italic=False, + color="BLUE", + background="BG_BLUE", + ), + even_row_style=TableRowStyle( + bold=False, + italic=False, + color="GREEN", + underline=True, + ), + odd_row_style=TableRowStyle( + bold=False, + italic=False, + color="YELLOW", + strikethrough=True, + ), + ) + +.. image:: https://github.com/CrispenGari/tabulato/blob/main/images/1.jpg?raw=true + :align: center + :width: 400 + +The table data can also be a list of python dictionaries. Here is an example of using a list of python dictionaries to generate a table. + +.. code-block:: python + + + data = [ + { + "name": "John Doe", + "student number": "S12345", + "dob": "1995-07-15", + "email": "john@example.com", + }, + { + "name": "Alice Smith", + "student number": "S67890", + "dob": "1998-03-22", + "email": "alice@example.com", + }, + { + "name": "Bob Johnson", + "student number": "S54321", + "dob": "1997-11-10", + "email": "bob@example.com", + }, + { + "name": "Emma Brown", + "student number": "S98765", + "dob": "1996-09-18", + "email": "emma@example.com", + }, + { + "name": "Michael Lee", + "student number": "S24680", + "dob": "1999-05-30", + "email": "michael@example.com", + }, + { + "name": "Sophia Wang", + "student number": "S13579", + "dob": "1994-12-05", + "email": "sophia@example.com", + }, + { + "name": "David Chen", + "student number": "S75310", + "dob": "1992-04-08", + "email": "david@example.com", + }, + { + "name": "Olivia Kim", + "student number": "S36924", + "dob": "1993-10-25", + "email": "olivia@example.com", + }, + ] + + colorful_tabulate( + data=data, + column_widths=[20, 20, 20, 30], + ) + + +The ``colorful_tabulate`` is a useful function for visually enhancing tabulated data in terminal output by applying colors and styling. The following are the parameters that this function takes. + +.. rst-class:: my-table + ++------------------+---------------------------------------+-----------------+----------------------------------------------------------------------------+----------+ +| Parameter | Description | Type | Default | Required | ++==================+=======================================+=================+============================================================================+==========+ +| data | The list of data to be displayed. | list | - | Yes | ++------------------+---------------------------------------+-----------------+----------------------------------------------------------------------------+----------+ +| headers | The list of column headers. | list | None | No | ++------------------+---------------------------------------+-----------------+----------------------------------------------------------------------------+----------+ +| colorful | Whether to display the table in color.| bool | True | No | ++------------------+---------------------------------------+-----------------+----------------------------------------------------------------------------+----------+ +| bold_header | Whether to display the header in bold.| bool | True | No | ++------------------+---------------------------------------+-----------------+----------------------------------------------------------------------------+----------+ +| header_style | Style for the header row. | TableRowStyle | TableRowStyle(bold=True, italic=False, color="BLUE", background=None) | No | ++------------------+---------------------------------------+-----------------+----------------------------------------------------------------------------+----------+ +| even_row_style | Style for even-numbered rows. | TableRowStyle | TableRowStyle(bold=False, italic=False, color="GREEN", background=None) | No | ++------------------+---------------------------------------+-----------------+----------------------------------------------------------------------------+----------+ +| odd_row_style | Style for odd-numbered rows. | TableRowStyle | TableRowStyle(bold=False, italic=False, color="YELLOW", background=None) | No | ++------------------+---------------------------------------+-----------------+----------------------------------------------------------------------------+----------+ +| column_widths | List of column widths. | list | [] | No | ++------------------+---------------------------------------+-----------------+----------------------------------------------------------------------------+----------+ + +The following are the color literals that can be passed to the ``color`` and ``background`` respectively. + +.. rst-class:: my-table + ++-----------+-------------+ +| Color | Description | ++===========+=============+ +| "BLACK" | Black | ++-----------+-------------+ +| "RED" | Red | ++-----------+-------------+ +| "GREEN" | Green | ++-----------+-------------+ +| "YELLOW" | Yellow | ++-----------+-------------+ +| "BLUE" | Blue | ++-----------+-------------+ +| "PURPLE" | Purple | ++-----------+-------------+ +| "CYAN" | Cyan | ++-----------+-------------+ +| "WHITE" | White | ++-----------+-------------+ + +.. rst-class:: my-table + ++--------------+-------------------+ +| Background | Description | ++==============+===================+ +| "BG_BLACK" | Black background | ++--------------+-------------------+ +| "BG_RED" | Red background | ++--------------+-------------------+ +| "BG_GREEN" | Green background | ++--------------+-------------------+ +| "BG_BLUE" | Blue background | ++--------------+-------------------+ +| "BG_PURPLE" | Purple background | ++--------------+-------------------+ +| "BG_CYAN" | Cyan background | ++--------------+-------------------+ +| "BG_WHITE" | White background | ++--------------+-------------------+ +| "BG_YELLOW" | Yellow background | ++--------------+-------------------+ + diff --git a/pyproject.toml b/pyproject.toml index 6dea37a..bb6e4d3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "tabulato" -version = "1.0.3" +version = "1.0.4" authors = [ {name = "Crispen Gari", email = "crispengari@gmail.com"}, ]