Add Documentation to Seiri with mkdocs

.github/workflows/deploy_docs.yml

@@ -0,0 +1,41 @@
+name: Deploy documentation
+
+# GitHub events that triggers the workflow:
+on:
+  push:
+    branches: ["main"]
+
+  pull_request:
+    branches: ["main"]
+
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Store cache ID
+        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - name: Create a key
+        uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Deploy documentation
+        run: |
+          pip install .[docs]
+          mkdocs gh-deploy --force

.github/workflows/seiri_test.yml

@@ -1,4 +1,4 @@
-name: seiri_test
+name: Test Seiri
 
 on:
   push:

README.md

@@ -1,6 +1,7 @@
 # Seiri
 [![tests](https://github.com/waseemr02/seiri/actions/workflows/seiri_test.yml/badge.svg?branch=main)](https://github.com/waseemr02/seiri/actions/workflows/seiri_test.yml)
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/2543d30ee224499a91a09b5c04b10454)](https://app.codacy.com/gh/waseemR02/seiri/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/2543d30ee224499a91a09b5c04b10454)](https://app.codacy.com/gh/waseemR02/seiri/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
 
 Tool for csv<->xlsx conversions and validation checks
 

docs/assets/javascripts/katex.js

@@ -0,0 +1,10 @@
+document$.subscribe(() => {
+  renderMathInElement(document.body, {
+    delimiters: [
+      { left: "$$",  right: "$$",  display: true },
+      { left: "$",   right: "$",   display: false },
+      { left: "\\(", right: "\\)", display: false },
+      { left: "\\[", right: "\\]", display: true }
+    ],
+  })
+})

docs/changelog.md

@@ -0,0 +1,40 @@
+---
+toc_depth: 1
+---
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+[Click here to see the unreleased changes.](https://github.com/waseemr02/seiri/compare/v1.2.0...HEAD)
+
+<!-- ### Fixed
+### Changed
+### Removed
+### Added -->
+
+## [1.2.0] - 2024-02-29
+
+### Added
+- Build seiri as a module with hachling and added it to the package ([#1])
+- Add coverage badge [#2]
+- Add mkdocs to the project and deploy it to github pages ([#2])
+
+### Changed
+- Coverage results are now deployed to codacy instead of github-pages ([#1]) and can be found [here](https://app.codacy.com/gh/waseemR02/seiri/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
+
+
+## [1.0.0] - 2024-02-26
+
+### Added
+
+- Seiri is an automation tool for handling csv<->xlsx transforms and validating against a specific set of rules
+- It is made to be cross-platform package instead of a script for better adoption to GUI
+- Tests were added under tests/ and it uses `pytest` which check the package against given csv and xlsx files to check if they are working as intended
+- Coverage results are deployed at every push to static page and can be checked in [here](https://waseemr02.github.io/seiri)
+
+[#2]: https://github.com/waseemR02/seiri/pull/2
+[#1]: https://github.com/waseemR02/seiri/pull/1
+[1.2.0]: https://github.com/waseemr02/seiri/releases/tag/v1.2.0
+[1.0.0]: https://github.com/waseemr02/seiri/releases/tag/v1.0.0

docs/index.md

@@ -0,0 +1,77 @@
+# Seiri
+[![tests](https://github.com/waseemr02/seiri/actions/workflows/seiri_test.yml/badge.svg?branch=main)](https://github.com/waseemr02/seiri/actions/workflows/seiri_test.yml)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/2543d30ee224499a91a09b5c04b10454)](https://app.codacy.com/gh/waseemR02/seiri/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/2543d30ee224499a91a09b5c04b10454)](https://app.codacy.com/gh/waseemR02/seiri/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
+
+Tool for csv$\Leftrightarrow$xlsx conversions and validation checks
+
+## Installation
+Create a virtual environment before installing dependencies
+```
+pip install .
+```
+
+## Usage
+This tool is written as library for future adaptation to gui
+
+But each class file can be run as a separate script
+
+### Transform
+```
+usage: transform.py [-h] [--cx CX] [-o OUTPUT] [--xc XC] [--log LOG] [-v]
+
+options:
+  -h, --help            show this help message and exit
+  --cx CX               Convert csv to xlsx
+  -o OUTPUT, --output OUTPUT
+                        output file
+  --xc XC               Convert xlsx to csv
+  --log LOG             path to log file
+  -v, --verbose
+```
+
+### Validate
+```
+usage: validate.py [-h] [--against AGAINST] [--log LOG] in_xlsx
+
+positional arguments:
+  in_xlsx            path to xlsx to validate
+
+options:
+  -h, --help         show this help message and exit
+  --against AGAINST  path to xlsx to validate against
+  --log LOG          path to log file
+```
+### Example Usage
+
+```
+python -m seiri.transform --cx tests/data/Sample.csv -o sample.xlsx --verbose
+```
+![csv_to_xlsx](assets/images/transform_csv_to_xlsx.png)
+-----------------
+```
+python -m seiri.validate tests/data/Delivered_correct.xlsx
+```
+![validation](assets/images/validate.png)
+```
+python -m seiri.transform --xc tests/data/Delivered_correct.xlsx -o sample.csv  --verbose
+```
+![xlsx_to_csv](assets/images/transform_csv_to_xlsx.png)
+
+## Testing
+Install the testing dependencies
+```
+pip install .[test]
+```
+
+Run the following
+```
+pytest -v
+```
+![pytest](assets/images/pytest.png)
+
+## Milestones
+- [$\checkmark$] Convert csv to xlsx
+- [$\checkmark$] Validating given Excel with rules
+- [$\checkmark$] Converting Excel to csv again
+- [$\checkmark$] Add Spell check on `en` column

docs/overrides/partials/toc-item.html

@@ -0,0 +1,43 @@
+<!--
+  Copyright (c) 2016-2024 Martin Donath <[email protected]>
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to
+  deal in the Software without restriction, including without limitation the
+  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+  sell copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in
+  all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+  IN THE SOFTWARE.
+-->
+
+<!-- Table of contents item -->
+<li class="md-nav__item">
+    <a href="{{ toc_item.url }}" class="md-nav__link">
+      <span class="md-ellipsis">
+        {{ toc_item.title }}
+      </span>
+    </a>
+
+    <!-- Table of contents list -->
+    {% if toc_item.children %}
+      <nav class="md-nav" aria-label="{{ toc_item.title | striptags }}">
+        <ul class="md-nav__list">
+          {% for toc_item in toc_item.children %}
+          {% if not page.meta.toc_depth or toc_item.level <= page.meta.toc_depth %}
+            {% include "partials/toc-item.html" %}
+          {% endif %}
+          {% endfor %}
+        </ul>
+      </nav>
+    {% endif %}
+  </li>

docs/reference/index.md

@@ -0,0 +1,8 @@
+# Seiri
+
+::: seiri
+
+In this section, you can find how Seiri's components are structured and how they interact with each other.
+
+- [transform.py](transform.md) – This contains all transforms (csv <-> xlsx) of `seiri`.
+- [validate.py](validate.md) – This contains all validation checks as mentioned in the Problem Statement for `seiri`

docs/reference/transform.md

@@ -0,0 +1,3 @@
+# Tranform
+
+::: seiri.transform

docs/reference/validate.md

@@ -0,0 +1,3 @@
+# Validate
+
+::: seiri.validate

mkdocs.yaml

@@ -0,0 +1,92 @@
+site_name: Seiri
+site_description: Automation Tool for csv<->xlsx transforms
+site_author: Waseem Riaz
+copyright: Copyright &copy; 2024 Waseem Riaz
+site_url: https://waseemr02.github.io/seiri
+repo_url: https://github.com/waseemr02/seiri
+repo_name: waseemr02/seiri
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+  custom_dir: docs/overrides
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/lightbulb-outline
+        name: "Switch to dark mode"
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/lightbulb
+        name: "Switch to light mode"
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  features:
+    - content.code.copy # the copy-to-clipboard buttons for code blocks
+    - content.action.view # view source button for pages
+    - navigation.footer # the previous and next buttons in the footer
+    - navigation.indexes # allow mother pages to have their own index pages
+    # - navigation.tabs # render classical type of navbar at top
+    - navigation.instant # instant navigation for faster page loads
+    - navigation.instant.prefetch # prefetch pages for instant navigation
+    - navigation.instant.progress # show progress bar for instant navigation
+    - navigation.top # back to top button
+    - search.highlight # highlight search results after going to a page
+    - search.suggest # show search suggestions while typing
+    - toc.follow # if toc sidebar doesn't fit, scroll to the active heading
+
+nav:
+  - Overview: index.md
+  # - User Guide: user_guide.md
+  - Reference:
+      - Reference: reference/index.md
+      - transform.py: reference/transform.md
+      - validate.py: reference/validate.md
+  - Changelog: changelog.md
+
+markdown_extensions:
+  # see https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/ for more pymdownx info
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.superfences
+  - pymdownx.tabbed: # content tabs
+      alternate_style: true
+  - toc:
+      permalink: true
+      title: Page contents
+  - admonition # blocks like note, warning, tip, etc.
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths:
+            - seiri
+          options:
+            members_order: source
+            show_bases: true
+            docstring_section_style: list
+            merge_init_into_class: true
+            show_docstring_attributes: true
+            docstring_style: google
+
+extra_javascript:
+  - assets/javascripts/katex.js
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/contrib/auto-render.min.js
+
+extra_css:
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.css

pyproject.toml

@@ -34,6 +34,11 @@ classifiers = [
 
 
 [project.optional-dependencies]
+docs = [
+    "mkdocs-material==9.5.9",      # to build docs
+    "mkdocstrings-python==1.8.0",  # to build reference documentation from docstrings
+]
+
 test = [
   'pytest==8.0.0',
   'coverage==7.4.1',

seiri/__init__.py

@@ -2,4 +2,4 @@
 
 Seire is an automation tool for csv<->xlsx conversions and validation checks
 """
-__version__ = "1.0.0"
+__version__ = "1.2.0"