Skip to content

Navigation Menu

Sign in
Appearance settings
Sign in
Sign up
Appearance settings

Commit daa4c40

Browse filesBrowse the repository at this point in the historyBrowse files
timkpainetimkpaine
authored
Redo documentation with diataxis (#247)
Signed-off-by: Tim Paine <3105306+timkpaine@users.noreply.github.com>
1 parent b7c7ac3 commit daa4c40
Copy full SHA for daa4c40

44 files changed

+3,034-2,255Lines changed: 3034 additions & 2255 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Dismiss banner
Expand file treeCollapse file tree
Open diff view settings
Collapse file

‎README.md‎

Copy file name to clipboardExpand all lines: README.md
+8-1Lines changed: 8 additions & 1 deletion
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,14 @@ We have taken these ideas a step further by introducing the concept of the `Mode
3333

3434
We aim to provide additional (and optional) tools for workflow orchestration on top of the configuration framework.
3535

36-
[More information is available in our wiki](https://github.com/Point72/ccflow/wiki)
36+
## Documentation
37+
38+
Our [wiki](https://github.com/Point72/ccflow/wiki) is organized along the four kinds of documentation:
39+
40+
- **[Tutorials](https://github.com/Point72/ccflow/wiki/Tutorials)** — hands-on lessons, from [First Steps](https://github.com/Point72/ccflow/wiki/First-Steps) through building ETL applications to a [configurable calculator driven from the CLI](https://github.com/Point72/ccflow/wiki/Building-a-Configurable-Calculator).
41+
- **[How-to Guides](https://github.com/Point72/ccflow/wiki/How-to-Guides)** — recipes for specific tasks like configuring complex values, caching, and retries.
42+
- **[Reference](https://github.com/Point72/ccflow/wiki/Reference)** — the core types, built-in models, and options.
43+
- **[Explanation](https://github.com/Point72/ccflow/wiki/Explanation)** — the [design goals](https://github.com/Point72/ccflow/wiki/Design-Goals), [core concepts](https://github.com/Point72/ccflow/wiki/Core-Concepts), and [why ccflow leans on Hydra](https://github.com/Point72/ccflow/wiki/Configuration-and-Hydra).
3744

3845
## Installation
3946

Collapse file

‎ccflow/examples/calculator/__init__.py‎

Copy file name to clipboard
+25Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
from pathlib import Path
2+
from typing import List, Optional
3+
4+
from ccflow import RootModelRegistry, load_config as load_config_base
5+
6+
__all__ = ("load_config",)
7+
8+
9+
def load_config(
10+
config_dir: str = "",
11+
config_name: str = "",
12+
overrides: Optional[List[str]] = None,
13+
*,
14+
overwrite: bool = True,
15+
basepath: str = "",
16+
) -> RootModelRegistry:
17+
return load_config_base(
18+
root_config_dir=str(Path(__file__).resolve().parent / "config"),
19+
root_config_name="base",
20+
config_dir=config_dir,
21+
config_name=config_name,
22+
overrides=overrides,
23+
overwrite=overwrite,
24+
basepath=basepath,
25+
)
Collapse file

‎ccflow/examples/calculator/__main__.py‎

Copy file name to clipboard
+33Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
import hydra
2+
3+
from ccflow.utils.hydra import cfg_run
4+
5+
__all__ = ("main",)
6+
7+
8+
@hydra.main(config_path="config", config_name="base", version_base=None)
9+
def main(cfg):
10+
cfg_run(cfg)
11+
12+
13+
# Run the default calculator (add) on some input:
14+
# python -m ccflow.examples.calculator +context.values=[1,2,3]
15+
#
16+
# Swap the calculation (function is in the defaults list, so no `+`):
17+
# python -m ccflow.examples.calculator function=scale +context.values=[1,2,3]
18+
#
19+
# Configure the selected function's field:
20+
# python -m ccflow.examples.calculator function=scale function.factor=10 +context.values=[1,2,3]
21+
# python -m ccflow.examples.calculator function=power function.exponent=3 +context.values=[1,2,3]
22+
#
23+
# A composed calculation (round the result of power):
24+
# python -m ccflow.examples.calculator function=rounded function.digits=1 +context.values=[1.5,2.5]
25+
#
26+
# A diamond that reuses a shared `mean` node, deduped by the graph + cache evaluator:
27+
# python -m ccflow.examples.calculator function=tail_ratio +context.values=[1,2,3,10]
28+
#
29+
# Inspect the composed configuration without running it:
30+
# python -m ccflow.examples.calculator.explain function=power
31+
32+
if __name__ == "__main__":
33+
main()
Collapse file

‎ccflow/examples/calculator/config/__init__.py‎

Copy file name to clipboardExpand all lines: ccflow/examples/calculator/config/__init__.py
Whitespace-only changes.
Collapse file

‎ccflow/examples/calculator/config/base.yaml‎

Copy file name to clipboard
+37Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# @package _global_
2+
3+
# Base configuration for the functional calculator example.
4+
#
5+
# The `function` config group selects which calculator runs, and the `output`
6+
# config group selects how the result is emitted (print, log, or write to file).
7+
#
8+
# Run the default calculator, printing the result:
9+
# python -m ccflow.examples.calculator +context.values=[1,2,3]
10+
# Swap the calculator (it is in the defaults list, so no `+`):
11+
# python -m ccflow.examples.calculator function=power +context.values=[1,2,3]
12+
# Configure the selected calculator's field:
13+
# python -m ccflow.examples.calculator function=power function.exponent=3 +context.values=[1,2,3]
14+
# Change how the result is emitted:
15+
# python -m ccflow.examples.calculator output=log +context.values=[1,2,3]
16+
# python -m ccflow.examples.calculator output=write +context.values=[1,2,3]
17+
# A diamond that reuses a shared `mean` node (deduped by the graph + cache evaluator below):
18+
# python -m ccflow.examples.calculator function=tail_ratio +context.values=[1,2,3,10]
19+
20+
defaults:
21+
- _self_
22+
- function: add
23+
- output: print
24+
25+
callable: /output
26+
27+
# Run every workflow under a graph + cache evaluator, so shared nodes in a
28+
# composed graph (e.g. the `mean` inside `tail_ratio`) are evaluated once.
29+
cli:
30+
model:
31+
_target_: ccflow.FlowOptions
32+
evaluator:
33+
_target_: ccflow.evaluators.MultiEvaluator
34+
evaluators:
35+
- _target_: ccflow.evaluators.GraphEvaluator
36+
- _target_: ccflow.evaluators.MemoryCacheEvaluator
37+
cacheable: true
Collapse file

‎ccflow/examples/calculator/config/function/add.yaml‎

Copy file name to clipboard
+2Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
_target_: ccflow.examples.calculator.functions.add
2+
offset: 0.0
Collapse file

‎ccflow/examples/calculator/config/function/power.yaml‎

Copy file name to clipboard
+2Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
_target_: ccflow.examples.calculator.functions.power
2+
exponent: 2.0
Collapse file

‎ccflow/examples/calculator/config/function/rounded.yaml‎

Copy file name to clipboard
+7Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Composes two functions: round the result of `power`.
2+
# `value` is a regular parameter fed by an upstream calculator model.
3+
_target_: ccflow.examples.calculator.functions.rounded
4+
digits: 2
5+
value:
6+
_target_: ccflow.examples.calculator.functions.power
7+
exponent: 2.0
Collapse file

‎ccflow/examples/calculator/config/function/scale.yaml‎

Copy file name to clipboard
+2Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
_target_: ccflow.examples.calculator.functions.scale
2+
factor: 1.0
Collapse file

‎ccflow/examples/calculator/config/function/tail_ratio.yaml‎

Copy file name to clipboard
+12Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# A diamond: tail_ratio needs upper_gap and lower_gap, and both need mean.
2+
# Under the graph + cache evaluator (see base.yaml), the shared mean is
3+
# computed once instead of once per branch.
4+
_target_: ccflow.examples.calculator.functions.tail_ratio
5+
upper:
6+
_target_: ccflow.examples.calculator.functions.upper_gap
7+
center:
8+
_target_: ccflow.examples.calculator.functions.mean
9+
lower:
10+
_target_: ccflow.examples.calculator.functions.lower_gap
11+
center:
12+
_target_: ccflow.examples.calculator.functions.mean

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.