add docs (#23)

lexdene · Mar 24, 2024 · abfdddd · abfdddd
1 parent 26918c2
commit abfdddd
Show file tree

Hide file tree

Showing 8 changed files with 277 additions and 187 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,14 @@
+version: 2
+
+build:
+  os: ubuntu-lts-latest
+  tools:
+    python: latest
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+formats:
+- pdf
+- epub
diff --git a/README.md b/README.md
@@ -1,188 +1,13 @@
 # Pangolier
 
-prometheus query builder
+build PromQL by Python code.
 
-## install
+[![pypi version]][pypi]
+[![Documentation Status]][Documentation]
 
-    pip install pangolier
+see docs at: https://pangolier.readthedocs.io
 
-## usage
-
-### simple case
-
-For a metric with filters:
-
-    from pangolier.metrics import Metric
-
-    print(Metric('http_requests_total').filter(
-        job='prometheus',
-        group='canary'
-    ).to_str())
-
-output:
-
-    http_requests_total{job="prometheus", group="canary"}
-
-### pretty output
-
-Add `pretty=True` in `to_str` for better readability:
-
-    from pangolier.metrics import Metric
-
-    print(Metric('http_requests_total').filter(
-        job='prometheus',
-        group='canary'
-    ).to_str(pretty=True))
-
-output:
-
-    http_requests_total{
-        job="prometheus",
-        group="canary"
-    }
-
-I will always use `pretty=True` in rest of this document.
-
-### functions
-
-Prometheus functions can be built by name. For example:
-
-    from pangolier.functions import function
-
-    abs = function('abs')
-    print(abs(Metric('http_requests_total')).to_str(pretty=True))
-
-output:
-
-    abs(
-        http_requests_total
-    )
-
-`range_function` should be used for functions accept a `range-vector`.
-
-    from pangolier.functions import range_function
-
-    rate = range_function('rate')
-    print(rate(Metric('http_requests_total'), timespan='5m').to_str(pretty=True))
-
-output:
-
-    rate(
-        http_requests_total[5m]
-    )
-
-`aggregation_operator` shoule be used for aggregation operators:
-
-    from pangolier.functions import aggregation_operator
-
-    sum_ = aggregation_operator('sum')
-    print(sum_(
-        Metric('http_requests_total'),
-        by=['job', 'group'],
-    ).to_str(pretty=True))
-
-output:
-
-    sum by(
-        job, group
-    )(
-        http_requests_total
-    )
-
-combine them all together:
-
-    histogram_quantile = function('histogram_quantile')
-    rate = range_function('rate')
-    sum_ = aggregation_operator('sum')
-
-    print(histogram_quantile(
-        0.9,
-        sum_(
-            rate(
-                Metric('http_request_duration_seconds_bucket'),
-                timespan='5m',
-            ),
-            by=['le']
-        )
-    ).to_str(pretty=True))
-
-output:
-
-    histogram_quantile(
-        0.9,
-        sum by(
-            le
-        )(
-            rate(
-                http_request_duration_seconds_bucket[5m]
-            )
-        )
-    )
-
-### binary operators
-
-support following binary operators:
-
-* `+` (addition)
-* `-` (subtraction)
-* `*` (multiplication)
-* `/` (division)
-* `%` (modulo)
-* `^` (power/exponentiation)
-
-For example, divide one metric with another:
-
-    from pangolier.metrics import Metric
-    from pangolier.functions import range_function
-
-    rate = range_function('rate')
-    print((
-        rate(
-            Metric('foo').filter(
-                group='canary'
-            ),
-            timespan='5m'
-        ) / rate(
-            Metric('bar').filter(
-                group='canary'
-            ),
-            timespan='5m'
-        )
-    ).to_str(pretty=True))
-
-output:
-
-    rate(
-        foo{
-            group="canary"
-        }[5m]
-    ) / rate(
-        bar{
-            group="canary"
-        }[5m]
-    )
-
-For operation with modifier:
-
-    from pangolier.metrics import Metric, BinOp, GroupLeft
-
-    print(BinOp(
-        '*',
-        Metric('foo'),
-        Metric('bar'),
-        on=['interface', 'job'],
-        group=GroupLeft('node', 'resource'),
-    ).to_str(pretty=True))
-
-output:
-
-    foo * on(
-        interface, job
-    ) group_left(
-        node, resource
-    ) bar
-
-
-## about name
-
-[Pangolier](https://dota2.fandom.com/wiki/Pangolier)
+[pypi version]: https://img.shields.io/pypi/v/pangolier
+[pypi]: https://pypi.org/project/pangolier
+[Documentation Status]: https://readthedocs.org/projects/pangolier/badge
+[Documentation]: https://pangolier.readthedocs.io
diff --git a/docs/about.rst b/docs/about.rst
@@ -0,0 +1,7 @@
+about
+=====
+
+about name
+----------
+
+`Pangolier <https://dota2.fandom.com/wiki/Pangolier>`_
diff --git a/docs/bin-op.rst b/docs/bin-op.rst
@@ -0,0 +1,71 @@
+binary operators
+================
+
+support following binary operators:
+
+* ``+`` (addition)
+* ``-`` (subtraction)
+* ``*`` (multiplication)
+* ``/`` (division)
+* ``%`` (modulo)
+* ``^`` (power/exponentiation)
+
+For example, divide one metric with another:
+
+.. code-block:: python
+
+   from pangolier.metrics import Metric
+   from pangolier.functions import range_function
+
+   rate = range_function('rate')
+   print((
+       rate(
+           Metric('foo').filter(
+               group='canary'
+           ),
+           timespan='5m'
+       ) / rate(
+           Metric('bar').filter(
+               group='canary'
+           ),
+           timespan='5m'
+       )
+   ).to_str(pretty=True))
+
+output:
+
+.. code-block::
+
+   rate(
+       foo{
+           group="canary"
+       }[5m]
+   ) / rate(
+       bar{
+           group="canary"
+       }[5m]
+   )
+
+For operation with modifier:
+
+.. code-block:: python
+
+   from pangolier.metrics import Metric, BinOp, GroupLeft
+
+   print(BinOp(
+       '*',
+       Metric('foo'),
+       Metric('bar'),
+       on=['interface', 'job'],
+       group=GroupLeft('node', 'resource'),
+   ).to_str(pretty=True))
+
+output:
+
+.. code-block::
+
+   foo * on(
+       interface, job
+   ) group_left(
+       node, resource
+   ) bar
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,3 @@
+project = 'pangolier'
+copyright = 'Attribution-NonCommercial-ShareAlike 4.0'
+version = '0.2.2'
diff --git a/docs/functions.rst b/docs/functions.rst
@@ -0,0 +1,97 @@
+functions
+=========
+
+Prometheus functions can be built by name. For example:
+
+.. code-block:: python
+
+   from pangolier.functions import function
+
+   abs = function('abs')
+   print(abs(
+       Metric('http_requests_total')
+   ).to_str(pretty=True))
+
+output:
+
+.. code-block::
+
+   abs(
+       http_requests_total
+   )
+
+``range_function`` should be used for functions accept a ``range-vector``.
+
+.. code-block:: python
+
+   from pangolier.functions import range_function
+
+   rate = range_function('rate')
+   print(rate(
+       Metric('http_requests_total'),
+       timespan='5m'
+   ).to_str(pretty=True))
+
+output:
+
+.. code-block::
+
+   rate(
+       http_requests_total[5m]
+   )
+
+``aggregation_operator`` shoule be used for aggregation operators:
+
+.. code-block:: python
+
+   from pangolier.functions import aggregation_operator
+
+   sum_ = aggregation_operator('sum')
+   print(sum_(
+       Metric('http_requests_total'),
+       by=['job', 'group'],
+   ).to_str(pretty=True))
+
+output:
+
+.. code-block::
+
+   sum by(
+       job, group
+   )(
+       http_requests_total
+   )
+
+combine them all together:
+
+.. code-block:: python
+
+   histogram_quantile = function('histogram_quantile')
+   rate = range_function('rate')
+   sum_ = aggregation_operator('sum')
+
+   print(histogram_quantile(
+       0.9,
+       sum_(
+           rate(
+               Metric('http_request_duration_seconds_bucket'),
+               timespan='5m',
+           ),
+           by=['le']
+       )
+   ).to_str(pretty=True))
+
+output:
+
+.. code-block::
+
+   histogram_quantile(
+       0.9,
+       sum by(
+           le
+       )(
+           rate(
+               http_request_duration_seconds_bucket[5m]
+           )
+       )
+   )