From 591f7ff792b5809984e770a8fa6da9816ddd8f62 Mon Sep 17 00:00:00 2001 From: Fabian Zills <46721498+PythonFZ@users.noreply.github.com> Date: Fri, 8 Mar 2024 11:30:00 +0100 Subject: [PATCH] small docs improvements (#757) --- docs/source/_get-started/api_classes.rst | 20 +++++++-------- docs/source/_get-started/index.rst | 5 ++-- docs/source/_get-started/project.rst | 8 +++--- docs/source/index.rst | 32 ++++++++++++++++++------ 4 files changed, 42 insertions(+), 23 deletions(-) diff --git a/docs/source/_get-started/api_classes.rst b/docs/source/_get-started/api_classes.rst index 4a9704df..c88a7842 100644 --- a/docs/source/_get-started/api_classes.rst +++ b/docs/source/_get-started/api_classes.rst @@ -14,30 +14,30 @@ Compared to the function-based approach, the class-based approach has several ad - Parameters, inputs, and outputs are handled as class attributes, simplifying the creation of new Nodes. To define a custom Node, simply inherit from the Node class. Parameters and outputs can be defined in two ways. -The ``from zntrack import zn`` module enables seamless integration with your existing workflows, allowing Python objects to be automatically serialized. - +The ``zntrack.`` enables seamless integration with your existing workflows, allowing Python objects to be automatically serialized. +Alternatively, you can use the ``zntrack.params_path()`` and ``zntrack.outs_path()`` to define the paths to the respective files. .. code-block:: python - from zntrack import Node, zn, Project + import zntrack - class SumValues(Node): + class SumValues(zntrack.Node): """Node to compute the sum of two parameters.""" - a = zn.params() - b = zn.params() + a = zntrack.params() + b = zntrack.params() - result = zn.outs() + result = zntrack.outs() def run(self): """Compute the sum of two parameters.""" self.result = self.a + self.b if __name__ == "__main__": - with Project() as project: + with zntrack.Project() as project: node = SumValues(a=1, b=2) project.run(repro=False) -We define our parameter using ``zn.params()`` and define the respective output using ``zn.outs()``. +We define our parameter using ``zntrack.params()`` and define the respective output using ``zntrack.outs()``. Gather results -------------- @@ -70,7 +70,7 @@ Explanation The same files as in the previous ``@nodify`` example are created. The main difference is the ``outs`` of our Node ``SumValues``. -Using the `zntrack.zn` module will store results in the Node Working Directory (``nwd``), +Using the `zntrack.outs` will store results in the Node Working Directory (``nwd``), It is typically set as ``nodes/``. The ``outs.json`` file is used, when calling ``node.load()`` to gather the results. diff --git a/docs/source/_get-started/index.rst b/docs/source/_get-started/index.rst index f3a4643c..332844f1 100644 --- a/docs/source/_get-started/index.rst +++ b/docs/source/_get-started/index.rst @@ -3,8 +3,9 @@ Getting started =============== -ZnTrack is designed to build workflows, track parameters and keep track of the associated outputs and metrics. Workflows are defined through Python script and human readable yaml files. The following sections will guide you through the basic concepts of ZnTrack and how to use it. - +ZnTrack is designed to build workflows, track parameters, and keep a record of associated outputs and metrics. +Workflows are defined through Python scripts and human-readable YAML files. +The following sections will guide you through the basic concepts of ZnTrack and how to use it. .. toctree:: :maxdepth: 0 diff --git a/docs/source/_get-started/project.rst b/docs/source/_get-started/project.rst index eadfc9a9..29d4579a 100644 --- a/docs/source/_get-started/project.rst +++ b/docs/source/_get-started/project.rst @@ -10,15 +10,15 @@ Let's assume the following two nodes: import zntrack class AddOne(zntrack.Node): - parameter: int = zntrack.zn.params() - outputs: int = zntrack.zn.outputs() + parameter: int = zntrack.params() + outputs: int = zntrack.outputs() def run(self): self.outputs = self.parameter + 1 class SubtractOne(zntrack.Node): - parameter: int = zntrack.zn.deps() - outputs: int = zntrack.zn.outputs() + parameter: int = zntrack.deps() + outputs: int = zntrack.outputs() def run(self): self.outputs = self.parameter - 1 diff --git a/docs/source/index.rst b/docs/source/index.rst index aa988d10..ee6376b3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,6 +3,8 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +.. _DVC: https://dvc.org/ + ZnTrack's documentation! ======================== @@ -15,7 +17,9 @@ ZnTrack's documentation! -ZnTrack is `zincware's `_ first developer package and in fact, the first released on PyPi, so we are glad you are here. ZnTrack is built to help you write code that can easily be shared and reproduced. +Welcome to ZnTrack, the first developer package from zincware _. +We're excited to have you on board! +ZnTrack is designed to simplify code sharing and reproducibility. - :ref:`userdoc-get-started` - :ref:`userdoc-examples` @@ -26,9 +30,23 @@ ZnTrack is `zincware's `_ first developer package a Example ========== -Here are two examples of how ZnTrack Nodes can look like. -ZnTrack supports function and class based Nodes, as well as the combination of both. -For more information, refer to the :ref:`userdoc-get-started` section. +With ZnTrack, you can construct a reproducible workflow using Nodes. +A Node, in this context, is a Python class or function with well-defined: + +* **Inputs:** Parameters and dependencies. +* **Outputs:** Files, metrics, and plots. +* **Code:** Function or class run method. + + +Nodes are connected by passing one node instance or attribute to another, similar to regular Python objects. +Unlike executing standard Python objects, ZnTrack enables you to define the workflow first, and the code is executed in a subsequent step. + +ZnTrack offers node tracking using DVC_, a Git-like version control system for data. +This feature provides automatic checkpoints, caching, and facilitates the effortless sharing of your workflow. + +Here are two examples illustrating what ZnTrack Nodes can look like. +ZnTrack supports both function and class-based Nodes, as well as a combination of both. +For detailed information, check out the :ref:userdoc-get-started section. Class based Node ---------------- @@ -37,10 +55,10 @@ Class based Node import zntrack class AddNumbers(zntrack.Node): - number1 = zntrack.zn.params() - number2 = zntrack.zn.params() + number1 = zntrack.params() + number2 = zntrack.params() - result = zntrack.zn.outs() + result = zntrack.outs() def run(self): self.result = self.number1 + self.number2