Improve docs (#495)

* update README.md * Update Documentation * configuration updates * add nodify * add API docs * add to docs * fix coding style * update docs * update documentation * test build documentation * updates * update docs * add section * ignore .ipynb_checkpoints and add blank line * update section
zincware · Feb 16, 2023 · ec2c0ed · ec2c0ed
1 parent cdc7877
commit ec2c0ed
Show file tree

Hide file tree

Showing 75 changed files with 2,108 additions and 38,679 deletions.
diff --git a/.github/workflows/pytest.yaml b/.github/workflows/pytest.yaml
@@ -79,3 +79,25 @@ jobs:
       - name: Pytest
         run: |
           poetry run pytest --nbmake ./examples
+
+  doctest:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: "3.11"
+      - name: Install Poetry
+        uses: abatilo/actions-poetry@v2
+        with:
+          poetry-version: 1.2.2
+      - name: Install package
+        run: |
+          sudo apt install pandoc
+          poetry config virtualenvs.create false
+          poetry install --with=docs
+      - name: Build documentation
+        run: |
+          cd ./docs
+          make html
diff --git a/.gitignore b/.gitignore
@@ -11,3 +11,4 @@ venv
 /py_track.egg-info/
 __pycache__/
 .pymon
+.ipynb_checkpoints
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -13,7 +13,7 @@ build:
     post_install:
       - pip install poetry
       - poetry config virtualenvs.create false
-      - poetry install
+      - poetry install --with=docs
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

diff --git a/README.md b/README.md
@@ -15,28 +15,26 @@
 
 ![Logo](https://raw.githubusercontent.com/zincware/ZnTrack/main/docs/source/img/zntrack.png)
 
-# Parameter Tracking for Python
-
-ZnTrack [zɪŋk træk] is an easy-to-use package for tracking parameters and creating computational graphs for your Python
-projects.
-What is a parameter? Anything set by a user in your code, for example, the number of
-layers in a neural network or the window size of a moving average.
-ZnTrack works by storing the values of parameters in Python classes and functions and
-monitoring how they change for several different runs.
-These changes can then be compared graphically to see what effect they had on your
-workflow.
-Beyond the standard tracking of parameters in a project, ZnTrack can be used to deploy
-jobs with a set of different parameter values, avoid the re-running of code components
-where parameters have not changed, and to identify computational bottlenecks.
-
-## Example
-ZnTrack is based on [DVC](https://dvc.org).
-With ZnTrack a DVC Node on the computational graph can be written as a Python class.
-DVC Options, such as parameters, input dependencies and output files are defined as class attributes.
-
-The following example shows a Node to compute a random number between 0 and a user defined maximum.
+# ZnTrack: A Parameter Tracking Package for Python
 
-````python
+ZnTrack ``zɪŋk træk`` is a lightweight and easy-to-use package for tracking parameters in your Python projects using DVC.
+With ZnTrack, you can define parameters in Python classes and monitor how they change over time.
+This information can then be used to compare the results of different runs, identify computational bottlenecks, and avoid the re-running of code components where parameters have not changed.
+
+## Key Features
+- Parameter, output and metric tracking: ZnTrack makes it easy to store and track the values of parameters in your Python code. It further allows you to store any outputs produced and gives an easy interface to define metrics.
+- Lightweight and database-free: Unlike other parameter tracking solutions, ZnTrack is lightweight and does not require any databases.
+
+## Getting Started
+To get started with ZnTrack, you can install it via pip: ```pip install zntrack```
+
+Next, you can start using ZnTrack to track parameters, outputs and metrics in your Python code.
+Here's an example of how to use ZnTrack to track the value of a parameter in a Python class.
+Start in an empty directory and run ``git init`` and ``dvc init`` for preparation.
+
+Then put the following into a python file called `hello_world.py` and call it with `python hello_world.py`.
+
+```python
 from zntrack import Node, zn
 from random import randrange
 
@@ -51,16 +49,17 @@ class HelloWorld(Node):
     def run(self):
         """Command to be run by DVC"""
         self.random_number = randrange(self.max_number)
-````
-
-This Node can then be put on the computational graph (writing the `dvc.yaml` and `params.yaml` files) by calling `write_graph()`. 
-The graph can then be executed e.g., through `dvc repro`.
+
+if __name__ == "__main__":
+    # Write the computational graph
+    HelloWorld(max_number=512).write_graph()
+```
 
-````python
-HelloWorld(max_number=512).write_graph()
-````    
+This will create a [DVC](https://dvc.org) stage ``HelloWorld``.
+The workflow is defined in ``dvc.yaml`` and the parameters are stored in ``params.yaml``.
 
-Once `dvc repro` is called, the results, i.e. the random number can be accessed directly by the Node object.
+You can run the workflow with ``dvc repro``.
+Once the graph is executed, the results, i.e. the random number can be accessed directly by the Node object.
 ```python
 hello_world = HelloWorld.load()
 print(hello_world.random_numer)
@@ -100,24 +99,6 @@ It handles all the computational overhead of reading config files, defining outp
 
 For more information on DVC visit their [homepage](https://dvc.org/doc).
 
-
-Installation
-============
-
-Install the stable version from PyPi via
-
-````shell
-pip install zntrack
-```` 
-
-or install the latest development version from source with:
-
-````shell
-git clone https://github.com/zincware/ZnTrack.git
-cd ZnTrack
-pip install .
-````
-
 Copyright
 =========
 

diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/make.bat b/docs/make.bat
@@ -10,8 +10,6 @@ if "%SPHINXBUILD%" == "" (
 set SOURCEDIR=source
 set BUILDDIR=build
 
-if "%1" == "" goto help
-
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	echo.
@@ -21,10 +19,12 @@ if errorlevel 9009 (
 	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
+	echo.https://www.sphinx-doc.org/
 	exit /b 1
 )
 
+if "%1" == "" goto help
+
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 

diff --git a/docs/source/_api/cli.rst b/docs/source/_api/cli.rst
@@ -0,0 +1,4 @@
+CLI
+===
+.. automodule:: zntrack.cli
+    :members:
diff --git a/docs/source/_api/core.rst b/docs/source/_api/core.rst
@@ -0,0 +1,4 @@
+Core
+====
+.. automodule:: zntrack.core
+    :members:
diff --git a/docs/source/_api/dvc.rst b/docs/source/_api/dvc.rst
@@ -0,0 +1,4 @@
+dvc
+====
+.. automodule:: zntrack.dvc
+    :members:
diff --git a/docs/source/_api/index.rst b/docs/source/_api/index.rst
@@ -0,0 +1,15 @@
+.. _userdoc-api:
+
+API Documentation
+=================
+
+.. toctree::
+    :maxdepth: 2
+
+    core
+    cli
+    utils
+    dvc
+    zn
+    meta
+    metadata
diff --git a/docs/source/_api/meta.rst b/docs/source/_api/meta.rst
@@ -0,0 +1,4 @@
+meta
+====
+.. automodule:: zntrack.meta
+    :members:
diff --git a/docs/source/_api/metadata.rst b/docs/source/_api/metadata.rst
@@ -0,0 +1,4 @@
+metadata
+========
+.. automodule:: zntrack.metadata
+    :members:
diff --git a/docs/source/_api/utils.rst b/docs/source/_api/utils.rst
@@ -0,0 +1,4 @@
+Utils
+=====
+.. automodule:: zntrack.utils
+    :members:
diff --git a/docs/source/_api/zn.rst b/docs/source/_api/zn.rst
@@ -0,0 +1,4 @@
+zn
+====
+.. automodule:: zntrack.zn
+    :members:
diff --git a/docs/source/_architecture/zntrack.core.functions.rst b/docs/source/_architecture/zntrack.core.functions.rst
diff --git a/docs/source/_architecture/zntrack.core.rst b/docs/source/_architecture/zntrack.core.rst
diff --git a/docs/source/_architecture/zntrack.descriptor.rst b/docs/source/_architecture/zntrack.descriptor.rst
diff --git a/docs/source/_architecture/zntrack.dvc.rst b/docs/source/_architecture/zntrack.dvc.rst
diff --git a/docs/source/_architecture/zntrack.interface.rst b/docs/source/_architecture/zntrack.interface.rst
diff --git a/docs/source/_architecture/zntrack.metadata.rst b/docs/source/_architecture/zntrack.metadata.rst