Close #13 Add Markdown Files

ARCHITECTURE.md

@@ -0,0 +1,84 @@
+# POIPath Architecture
+
+*POIPath*'s intention is to deliver easy means for testing the correctness of generated
+`XWPFDocument`s or `XSSFWorkbook`s. It was developed for the [jocument](https://github.com/DDS-GmbH/jocument)
+library, which wraps a template engine around Apache POI.
+
+## Design
+
+The design idea is to have wrapper classes (or [Java Records](https://docs.oracle.com/javase/specs/jls/se14/preview/specs/records-jls.html))
+on each XWPF/XSS element to quickly navigate through a document structure and parse the
+actual content out of it. The following example shows how to access a date cell of an
+`XSSWorkbook`:
+
+```java
+package org.example.popath;
+
+import java.util.LocalDate;
+import com.docutools.poipath.PoiPath;
+import com.docutools.poipath.xssf.*;
+import import org.apache.poi.xssf.usermodel.XSSFWorkbook;
+
+public class PoiPathExample {
+
+  public static void main(String[] args) {
+    try(var workbook = new XSSFWorkbook(new File(args[0]))) {
+      LocalDate date = PoiPath.xssf(workbook)
+          .sheet(0)
+          .row(0)
+          .cell(0)
+          .dateValue();
+
+      assert date.equals(LocalDate.of(2000, 1, 1));
+    }
+  }
+
+}
+```
+
+## Code Map
+
+### [PoiPath](src/main/java/com/docutools/poipath/PoiPath.java)
+
+Entrypoint to load the corresponding wrapper class for the given POI document.
+
+### [com.docutools.poipath.xssf](src/main/java/com/docutools/poipath/xssf)
+
+This package contains all wrapper recrods to navigate through `XSSFWorkbook`s.
+
+### [com.docutools.poipath.xwpf](src/main/java/com/docutools/poipath/xwpf)
+
+This package contains all wrapper records to navigate through `XWPFDocument`s.
+
+## Corss-Cutting Concerns
+
+### Testing
+
+Test files (`.XLSX` or `.DOCX`) are added as resources to [src/test/resources](src/test/resources)
+within the corresponding file type folder.
+
+We provide easy resource loading via the utility classes:
+
+* [Documents](src/test/java/com/docutools/poipath/Documents.java)
+* [Workbooks](src/test/java/com/docutools/poipath/Workbooks.java)
+
+A typical test case may look like:
+
+```java
+package com.docutools.poipath.xssf;
+
+import java.io.IOException;
+import org.junit.jupiter.api.Test;
+import com.docutools.poipath.Workbooks;
+
+class SomeXssfTests {
+
+  @Test
+  void someXssfTest() throws IOException {
+    try(var workbook = Workbooks.resource("/XSSF/myExcelResource.xlsx")) {
+      assert PoiPath.xssf(workbook).numberOfSheets() == 2;
+    }
+  }
+
+}
+```

CONTRIBUTE.md

@@ -0,0 +1,28 @@
+# Contributing
+When contributing to this repository, please first discuss the change you wish to make via issue,
+email, or any other method with the owners of this repository before making a change. 
+
+## We Develop with Github
+We use github to host code, to track issues and feature requests, as well as accept pull requests.
+
+## We Use [Github Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests
+Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests:
+
+1. Fork the repo and create your branch from `master`.
+2. If you've added code that should be tested, add tests.
+3. If you've changed APIs, update the documentation.
+4. Ensure the test suite passes.
+5. Make sure your code lints.
+6. Issue that pull request!
+
+## Any contributions you make will be under the MIT Software License
+In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern.
+
+## Report bugs using Github's [issues](https://github.com/DDS-GmbH/poipath/issues)
+We use GitHub issues to track public bugs. Report a bug by [opening a new issue](); it's that easy!
+
+## Use a Consistent Coding Style
+
+This project is using [Checkstyle](https://checkstyle.sourceforge.io/) to ensure a shared code style is enforced.
+
+You can find the checkstyle conventions in [this file](config/checkstyle/checkstyle.xml), which can be imported to any current JAVA IDE.

README.md

@@ -0,0 +1,68 @@
+# poipath
+> Testing library for [Apache POI](https://poi.apache.org/) documents.
+
+*poipath* let's you easily navigate through [XSSFWorkbook](https://poi.apache.org/apidocs/dev/org/apache/poi/xssf/usermodel/XSSFWorkbook.html)
+or [XWPFDocument](https://poi.apache.org/apidocs/dev/org/apache/poi/xwpf/usermodel/XWPFDocument.html)
+datastructures from *Apache POI* which can be quite useful in testing.
+
+```xml
+<dependency>
+  <groupId>com.docu-tools</groupId>
+  <artifactId>poipath</artifactId>
+  <version>1.0.0</version>
+</dependency>
+```
+
+Here an example for testing an Excel report:
+
+```java
+package myreportingapp;
+
+import java.io.File;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Assertions;
+import com.docutools.poipath.PoiPath;
+import org.apache.poi.xssf.usermodel.XSSFWorkbook;
+
+class TestReports {
+
+  @Test
+  void testMyReport() throws Exception {
+    try(var report = PoiPath.xssf(new XSSFWorkbook(new File("/path/to/file.xlsx")))) {
+
+      Assertions.assertEquals(report.sheet("Overview")
+          .row(2).cell(3).dateValue(), LocalDate.of(2021, 12, 13));
+
+      Assertions.assertEquals(report.sheet("Overview")
+          .row(3).cell(3).stringValue(), "Performance Report");
+
+    }
+  }
+
+}
+```
+
+## Feature Overview
+
+### XSSF
+
+- [x] Navigate Sheets, Rows, Cells
+- [x] Extract primitively typed values based on cell type (Number, String, Boolean)
+- [x] Get raw and executed formulas
+- [x] Parse dates
+- [ ] Monetary amounts
+- [ ] Control elements
+- [ ] Pictures or diagrams
+- [ ] Header/footer
+- [ ] Document/page settings
+
+### XWPF
+
+- [x] Navigate body elements (paragraphs and tables)
+- [x] Extract runs and pictures from paragraphs
+- [x] Extract rows and cells from tables
+- [x] Easily load full text from paragraphs and table cells
+- [ ] Header/footer
+- [ ] Document/page settings
+- [ ] Footer notes
+- [ ] Table of contents