Merge pull request #36 from dbatten5/docs

Docs

.github/workflows/tests.yml

@@ -149,4 +149,4 @@ jobs:
           nox --session=coverage -- xml
 
       - name: Upload coverage report
-        uses: codecov/codecov-action@3.1.2
+        uses: codecov/codecov-action@v3

docs/index.md

@@ -6,15 +6,16 @@ end-before: <!-- github-only -->
 
 [license]: license
 [contributor guide]: contributing
-[command-line reference]: usage
+
+<!-- [command-line reference]: usage -->
 
 ```{toctree}
 ---
 hidden:
 maxdepth: 1
 ---
 
-<!-- usage -->
+usage
 reference
 contributing
 Code of Conduct <codeofconduct>

docs/usage.md

@@ -1,7 +1,143 @@
 # Usage
 
-```{eval-rst}
-.. click:: arraytex.__main__:main
-    :prog: arraytex
-    :nested: full
+<!-- ```{eval-rst} -->
+<!-- .. click:: arraytex.__main__:main -->
+<!--     :prog: arraytex -->
+<!--     :nested: full -->
+<!-- ``` -->
+
+Suppose you want to convert a `numpy.NDArray` object to a LaTeX representation:
+
+```python
+>>> import numpy as np
+>>> A = np.arange(6).reshape(2, 3)
+>>> A
+array([[0, 1, 2],
+       [3, 4, 5]])
+```
+
+## To matrix
+
+First import the `to_matrix` function:
+
+```python
+>>> from arraytex import to_matrix
+```
+
+Then run `to_matrix` with a `numpy.NDArray` object as the first argument:
+
+```python
+>>> print(to_matrix(A))
+\begin{bmatrix}
+0 & 1 & 2 \\
+3 & 4 & 5 \\
+\end{bmatrix}
+```
+
+Different matrix style environment delimiters can be used:
+
+```python
+>>> print(to_matrix(A, style="p"))
+\begin{pmatrix}
+0 & 1 & 2 \\
+3 & 4 & 5 \\
+\end{pmatrix}
+```
+
+So can builtin number formatters:
+
+```python
+>>> print(to_matrix(A, num_format=".2e"))
+\begin{bmatrix}
+0.00\mathrm{e}{+00} & 1.00\mathrm{e}{+00} & 2.00\mathrm{e}{+00} \\
+3.00\mathrm{e}{+00} & 4.00\mathrm{e}{+00} & 5.00\mathrm{e}{+00} \\
+\end{bmatrix}
+```
+
+Prefer scientific notation to e-notation? No problem:
+
+```python
+>>> print(to_matrix(A, num_format=".2e", scientific_notation=True))
+\begin{bmatrix}
+0.00 \times 10^{+00} & 1.00 \times 10^{+00} & 2.00 \times 10^{+00} \\
+3.00 \times 10^{+00} & 4.00 \times 10^{+00} & 5.00 \times 10^{+00} \\
+\end{bmatrix}
+```
+
+## To tabular
+
+First import the `to_tabular` function:
+
+```python
+>>> from arraytex import to_tabular
+```
+
+Then run `to_tabular` with a `numpy.NDArray` as the first argument:
+
+```python
+>>> print(to_tabular(A))
+\begin{tabular}{c c c}
+\toprule
+Col 1 & Col 2 & Col 3 \\
+\midrule
+0 & 1 & 2 \\
+3 & 4 & 5 \\
+\bottomrule
+\end{tabular}
+```
+
+The `num_format` and `scientific_notation` arguments are available to use:
+
+```python
+>>> print(to_tabular(A, num_format=".2f"))
+\begin{tabular}{c c c}
+\toprule
+Col 1 & Col 2 & Col 3 \\
+\midrule
+0.00 & 1.00 & 2.00 \\
+3.00 & 4.00 & 5.00 \\
+\bottomrule
+\end{tabular}
+```
+
+You can pass custom column names and column align identifiers:
+
+```python
+>>> print(to_tabular(A, col_align=["l", "c", "r"], col_names=["Data", "More Data", "Even More Data"]))
+\begin{tabular}{l c r}
+\toprule
+Data & More Data & Even More Data \\
+\midrule
+0 & 1 & 2 \\
+3 & 4 & 5 \\
+\bottomrule
+\end{tabular}
+```
+
+Pass a list of column indices:
+
+```python
+>>> print(to_tabular(A, col_index=["Sample 1", "Sample 2"]))
+\begin{tabular}{l c c c}
+\toprule
+Index & Col 1 & Col 2 & Col 3 \\
+\midrule
+Sample 1 & 0 & 1 & 2 \\
+Sample 2 & 3 & 4 & 5 \\
+\bottomrule
+\end{tabular}
+```
+
+Specify the name of the name of index column through `col_names`:
+
+```python
+>>> print(to_tabular(A, col_index=["Sample 1", "Sample 2"], col_names=["Which Sample", "A", "B", "C"]))
+\begin{tabular}{l c c c}
+\toprule
+Which Sample & A & B & C \\
+\midrule
+Sample 1 & 0 & 1 & 2 \\
+Sample 2 & 3 & 4 & 5 \\
+\bottomrule
+\end{tabular}
 ```

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "arraytex"
-version = "0.0.7"
+version = "0.0.8"
 description = "ArrayTeX"
 authors = ["Dom Batten <[email protected]>"]
 license = "MIT"

src/arraytex/api.py

@@ -82,8 +82,8 @@ def to_tabular(
 
     Raises:
         TooManyDimensionsError: when the supplied array has more than 2 dimensions
-        DimensionMismatchError: when there are mismatched column identifiers and
-            dimensions
+        DimensionMismatchError: when there is a mismatch between column items and number
+            of columns, or column index items and number of rows
     """
     n_dims = len(arr.shape)
 

src/arraytex/utils.py

@@ -61,7 +61,7 @@ def num_formatter(x: Union[np.int64, np.float64, np.float32]) -> str:
     )
 
     if num_format and "e" in num_format:
-        pattern = r"e(-?\d+)"
+        pattern = r"e([\+-]?\d+)"
         replace = r"\\mathrm{e}{\g<1>}"
         if scientific_notation:
             replace = r" \\times 10^{\g<1>}"

tests/test_api.py

@@ -87,6 +87,20 @@ def test_e_notation(self) -> None:
             == r"""\begin{bmatrix}
 1.00\mathrm{e}{-03} & 2.00\mathrm{e}{-03} & 3.00\mathrm{e}{-03} \\
 4.00\mathrm{e}{-03} & 5.00\mathrm{e}{-03} & 6.00\mathrm{e}{-03} \\
+\end{bmatrix}"""
+        )
+
+    def test_e_notation_positive(self) -> None:
+        """Scientific E notation can be selected with positive powers."""
+        mat = np.arange(6).reshape(2, 3)
+
+        out = to_matrix(mat, num_format=".2e")
+
+        assert (
+            out
+            == r"""\begin{bmatrix}
+0.00\mathrm{e}{+00} & 1.00\mathrm{e}{+00} & 2.00\mathrm{e}{+00} \\
+3.00\mathrm{e}{+00} & 4.00\mathrm{e}{+00} & 5.00\mathrm{e}{+00} \\
 \end{bmatrix}"""
         )