add documentation. (#98)

* add documentation.

* fix

* fix

* Update parameters.md

* fix

* fix

Author: Yusuke Oda

README.md

@@ -1,27 +1,55 @@
-# latexify_py
-A Python package that generates LaTeX math description from Python functions.
+# `latexify`
+
+`latexify` is a Python package to compile a fragment of Python source code to a
+corresponding $\LaTeX$ expression.
+
+`latexify` provides the following functionalities:
+
+* Libraries to compile Python source code or AST to $\LaTeX$.
+* IPython classes to pretty-print compiled functions.
+
 
 ## FAQs
-1. Which Python version? ... Using 3.10 AST.
-2. GPT-3? ... No, rule-based.
 
-## Installation
+1. *Which Python versions are supported?*
+
+   Syntaxes on **Pythons 3.7 to 3.10** are officially supported, or will be supported.
+
+2. *Which technique is used?*
+
+   `latexify` is implemented as a rule-based system on the official `ast` package.
 
-```shell
-pip install latexify-py
-```
+3. *Are "AI" techniques adopted?*
 
-## Example
+   `latexify` is based on traditional parsing techniques.
+   If the "AI" meant some techniques around machine learning, the answer is no.
 
-Follow provided example on [Google Colaboratory](https://colab.research.google.com/drive/1MuiawKpVIZ12MWwyYuzZHmbKThdM5wNJ?usp=sharing).
 
-## How to Contribute 
-To contribute to this Project refer [CONTRIBUTING.md](https://github.com/google/latexify_py/blob/develop/CONTRIBUTING.md) file.
+## Getting started
+
+We prepared a
+[Google Colaboratory notebook](https://colab.research.google.com/drive/1MuiawKpVIZ12MWwyYuzZHmbKThdM5wNJ?usp=sharing)
+that provides several examples to use this package.
+
+See also the official [documentation](docs/index.md) for more details.
+
+## How to Contribute
+
+To contribute to this project, please refer
+[CONTRIBUTING.md](https://github.com/google/latexify_py/blob/develop/CONTRIBUTING.md).
+
 
 ## Disclaimer
 
-This is not an officially supported Google product.
+This software is currently hosted on https://github.com/google, but not officially
+supported by Google.
+
+If you have any issues and/or questions about this software, please visit the
+[issue tracker](https://github.com/google/latexify_py/issues)
+or contact the [main maintainer](https://github.com/odashi).
+
 
 ## License 
 
-This Repository follows [Apache License 2.0](https://github.com/google/latexify_py/blob/develop/LICENSE).
+This software adopts the
+[Apache License 2.0](https://github.com/google/latexify_py/blob/develop/LICENSE).

docs/getting_started.md

@@ -0,0 +1,89 @@
+# Getting started
+
+This document describes how to use `latexify` with your Python code.
+
+
+## Installation
+
+`lateixfy` depends on only Python libraries at this point.
+You can simply install `latexify` via `pip`:
+
+```shell
+$ pip install latexify-py
+```
+
+Note that you have to install `latexify-py` rather than `latexify`.
+
+
+## Using `latexify` in Jupyter
+
+`latexify.function` decorator function wraps your functions to pretty-print them as
+corresponding LaTeX formulas.
+Jupyter recoginzes this wrapper and try to print LaTeX instead of the original function.
+
+The following snippet:
+
+```python
+@latexify.function
+def solve(a, b, c):
+    return (-b + math.sqrt(b**2 - 4 * a * c)) / (2 * a)
+
+solve
+```
+
+will print the following formula to the output:
+
+$$ \mathrm{solve}(a, b, c) = \frac{-b + \sqrt{b^2 - 4ac}}{2a} $$
+
+
+Invoking wrapped functions work transparently as the original function.
+
+```python
+solve(1, 2, 1)
+```
+
+```
+-1.0
+```
+
+Applying `str` to the wrapped function returns the underlying LaTeX source.
+
+```python
+print(solve)
+```
+
+```
+\\mathrm{f}(n) = \\frac{-b + \\sqrt{b^{{2}} - {4}ac}}{{2}a}
+```
+
+`latexify.expression` works similarly to `latexify.function`,
+but it prints the function without its signature:
+```python
+@latexify.expression
+def solve(a, b, c):
+    return (-b + math.sqrt(b**2 - 4 * a * c)) / (2 * a)
+
+solve
+```
+
+$$ \frac{-b + \sqrt{b^2 - 4ac}}{2a} $$
+
+
+## Obtaining LaTeX expression directly
+
+You can also use `latexify.get_latex`, which takes a function and directly returns the
+LaTeX expression corresponding to the given function.
+
+The same parameters with `latexify.function` can be applied to `latexify.get_latex` as
+well.
+
+```python
+def solve(a, b, c):
+    return (-b + math.sqrt(b**2 - 4 * a * c)) / (2 * a)
+
+latexify.get_latex(solve)
+```
+
+```
+\\mathrm{f}(n) = \\frac{-b + \\sqrt{b^{{2}} - {4}ac}}{{2}a}
+```

docs/index.md

@@ -0,0 +1,10 @@
+# `latexify` documentation
+
+## Index
+
+* [Getting started](getting_started.md)
+* [Parameters](parameters.md)
+
+## External resources
+
+* [Examples on Google Colaboratory](https://colab.research.google.com/drive/1MuiawKpVIZ12MWwyYuzZHmbKThdM5wNJ?usp=sharing)

docs/parameters.md

@@ -0,0 +1,109 @@
+# `latexify` parameters
+
+This document describes the list of parameters to control the behavior of `latexify`.
+
+
+## `identifiers: dict[str, str]`
+
+Key-value pair of identifiers to replace.
+
+```python
+identifiers = {
+    "my_function": "f",
+    "my_inner_function": "g",
+    "my_argument": "x",
+}
+
+@latexify.function(identifiers=identifiers)
+def my_function(my_argument):
+    return my_inner_function(my_argument)
+
+my_function
+```
+
+$$\mathrm{f}(x) = \mathrm{g}\left(x\right)$$
+
+
+## `reduce_assignments: bool`
+
+Whether to compose all variables defined before the `return` statement.
+
+The current version of `latexify` recognizes only the assignment statements.
+Analyzing functions with other control flows may raise errors.
+
+```python
+@latexify.function(reduce_assignments=True)
+def f(a, b, c):
+    discriminant = b**2 - 4 * a * c
+    numerator = -b + math.sqrt(discriminant)
+    denominator = 2 * a
+    return numerator / denominator
+
+f
+```
+
+$$\mathrm{f}(a, b, c) = \frac{-b + \sqrt{b^{{2}} - {4} a c}}{{2} a}$$
+
+
+## `use_math_symbols: bool`
+
+Whether to automatically convert variables with symbol names into LaTeX symbols or not.
+
+```python
+@latexify.function(use_math_symbols=True)
+def greek(alpha, beta, gamma, Omega):
+  return alpha * beta + math.gamma(gamma) + Omega
+
+greek
+```
+
+$$\mathrm{greek}({\alpha}, {\beta}, {\gamma}, {\Omega}) = {\alpha} {\beta} + \Gamma\left({{\gamma}}\right) + {\Omega}$$
+
+
+## `use_raw_function_name: bool`
+
+Whether to use the original string as the function name or not.
+
+```python
+@latexify.function(use_raw_function_name=True)
+def quadratic_solution(a, b, c):
+    return (-b + math.sqrt(b**2 - 4 * a * c)) / (2 * a)
+
+f
+```
+
+$$\mathrm{quadratic\_solution}(a, b, c) = \frac{-b + \sqrt{b^{{2}} - {4} a c}}{{2} a}$$
+
+(note that GitHub's LaTeX renderrer does not process underscores correctly.)
+
+## `use_set_symbols: bool`
+
+Whether to use binary operators for set operations or not.
+
+```python
+@latexify.function(use_set_symbols=True)
+def f(x, y):
+    return x & y, x | y, x - y, x ^ y, x < y, x <= y, x > y, x >= y
+
+f
+```
+
+$$\mathrm{f}(x, y) = \left( x \cap y\space,\space x \cup y\space,\space x \setminus y\space,\space x \mathbin{\triangle} y\space,\space {x \subset y}\space,\space {x \subseteq y}\space,\space {x \supset y}\space,\space {x \supseteq y}\right)$$
+
+
+## `use_signature: bool`
+
+Whether to output the function signature or not.
+
+The default value of this flag depends on the frontend function.
+`True` is used in `latexify.function`, while `False` is used in `latexify.expression`.
+
+```python
+@latexify.function(use_signature=False)
+def f(a, b, c):
+    return (-b + math.sqrt(b**2 - 4 * a * c)) / (2 * a)
+
+f
+```
+
+$$\frac{-b + \sqrt{b^{{2}} - {4} a c}}{{2} a}$$