{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "088d71e7-7866-4878-8141-cd9ed89a619d",
   "metadata": {},
   "source": [
    "# Getting Started"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4a8e7f9d-874e-4d61-83d0-fcbc3d4571b2",
   "metadata": {},
   "source": [
    "## Install `doitoml`\n",
    "\n",
    "Use your python package manager of choice to install a release of `doitoml`:\n",
    "\n",
    "````{tab-set}\n",
    "\n",
    "```{tab-item} PyPI\n",
    "~~~bash\n",
    "pip install doitoml\n",
    "~~~\n",
    "```\n",
    "\n",
    "```{tab-item} conda-forge\n",
    "~~~bash\n",
    "mamba install -c conda-forge doitoml\n",
    "~~~\n",
    "\n",
    "or\n",
    "\n",
    "~~~bash\n",
    "conda install -c conda-forge doitoml\n",
    "~~~\n",
    "```\n",
    "\n",
    "````"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6dd7545e-c0de-488c-bfd2-b35395159b46",
   "metadata": {},
   "source": [
    "<details>\n",
    "\n",
    "<summary>This will install...</summary>\n",
    "\n",
    "- `doitoml` and its dependencies\n",
    "  - `doit[toml]`\n",
    "  - `tomli` (if you're on python <3.11)\n",
    "\n",
    "</details>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0eacfb47-fc26-4759-9814-5c7022b02a27",
   "metadata": {},
   "source": [
    "## Configure `doit`\n",
    "\n",
    "Like many Python-based tools, `doit` prefers finding its [configuration in `pyproject.toml`](https://pydoit.org/configuration.html#pyproject-toml) under the `[tool.doit]` prefix. \n",
    "\n",
    "`doitoml` provide an _entry point_ for `doit.LOADER`, which offers task discovery features from files. As an alternative, advanced users of `dodo.py` can use the Python API."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "79a1fc43-bc02-465e-9da4-87a216641d9a",
   "metadata": {},
   "source": [
    "```toml\n",
    "# pyproject.toml\n",
    "[tool.doit]\n",
    "loader = \"doitoml\"\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fa07811e-e8d4-4f63-b858-82bf60bf2696",
   "metadata": {},
   "source": [
    "### Schema\n",
    "\n",
    "A partial [schema](../reference/schema.md) for the `doit` and `doitoml`-relevant parts of `pyproject.toml` is available. \n",
    "\n",
    "Note that this is fairly incomplete, and doesn't work very well with community-based systems such as [schemastore.org](https://www.schemastore.org/json/)\n",
    "\n",
    "Using the [taplo](https://github.com/tamasfe/taplo) language server, a `pyproject.toml` may declare a schema with either the standards-based `$schema` property:\n",
    "\n",
    "```toml\n",
    "\"$schema\" = \"https://doitoml.rtfd.io/en/latest/_static/_pyproject.v0.schema.json\"\n",
    "```\n",
    "\n",
    "...or the `taplo`-specific directive:\n",
    "\n",
    "```toml\n",
    "#:schema https://doitoml.rtfd.io/en/latest/_static/_pyproject.v0.schema.json\n",
    "```\n",
    "\n",
    "...or via explicit configuration.\n",
    "\n",
    "Similarly, the `package.json` counterpart (which _can't_ configure `doit`) is available as:\n",
    "\n",
    "```json\n",
    "{\n",
    "    \"$schema\": \"https://doitoml.rtfd.io/en/latest/_static/_jspackage.v0.schema.json\"\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "632224c6-25aa-4356-b17a-6e290e6c8f2b",
   "metadata": {},
   "source": [
    "#### Local Schema\n",
    "\n",
    "To get a local copy of the schema which includes custom schema as defined by first- and third-party addons, use `python -m doitoml.schema.dump`. \n",
    "\n",
    "This could be combined with a community-maintained schema such as [schemastore.org](https://schemastore.org) to handle other well-known tools."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3b1f4e68-f109-4d2d-a9ba-0947b7aee720",
   "metadata": {},
   "outputs": [],
   "source": [
    "!python -m doitoml.schema.dump --help"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "24063e10-abfb-4fca-8c1f-66cba217db68",
   "metadata": {},
   "source": [
    "### Write Tasks\n",
    "\n",
    "_Tasks_ are the most important part of using `doit`. These are written in the `[tool.doitoml.tasks]` prefix. For readability, it's encouraged to fully write out tasks in their own sections."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "581b0d9a-fe40-40cd-aca9-d51b096b1b8a",
   "metadata": {},
   "source": [
    "```toml\n",
    "# pyproject.toml\n",
    "[tool.doit]\n",
    "loader = \"doitoml\"\n",
    "\n",
    "[tool.doitoml.tasks.hello]\n",
    "actions = ['echo \"hello world\"']\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1fd67b3-9a4f-4b96-9ede-6464ee110c06",
   "metadata": {},
   "source": [
    "> **Note**\n",
    ">\n",
    ">While the above, cross-platform _shell_ task is simple and powerful, this pattern inroduces a number of risks around shell escaping. Keep reading for more about other kinds of tasks."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0c064136-ccdf-48d5-bb4a-21c788e6a057",
   "metadata": {},
   "source": [
    "### Parts of tasks\n",
    "\n",
    "Even in vanilla `doit`, there are a large number of configurable options. Few tasks will need close to all of them, but a few are worth pointing out:\n",
    "\n",
    "| field | kind | description |\n",
    "|-|-|-|\n",
    "| `actions` | list of (strings or list of strings) | the raw shell command or shell tokens \n",
    "| `targets` | list of paths | files created or modified by a task\n",
    "| `file_dep` | list of paths | files that, when changed, will cause a task to be run \n",
    "| `task_dep` | list of fully-qualified _task ids_ | the names (with optional `*` wildcards) of any _other_ tasks that need to have been run before a task\n",
    "| `doc` | string | a text description of a task\n",
    "| `meta` | dict | a dictionary of extra values, not used directly by `doit`\n",
    "| `uptodate` | list of (string, bool or dict) | update checkers that complement `file_dep` and `task_dep`\n",
    "\n",
    "See the [cheatsheet](../reference/cheatsheet.md) for more."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "57e81863-1520-444d-b87f-c7d9564a74c7",
   "metadata": {},
   "source": [
    "## Use `doit`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e4e692f9-7a7d-4e33-ad88-407c865a6cb3",
   "metadata": {},
   "source": [
    "### Run Tasks\n",
    "\n",
    "By default, `doit [run]` will run **all** known tasks.\n",
    "\n",
    "```bash\n",
    "doit\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "64892611-b5ab-4868-a68b-343cddc15d61",
   "metadata": {},
   "source": [
    "### List Tasks\n",
    "\n",
    "Now you are ready to start working with your tasks:\n",
    "\n",
    "```bash\n",
    "doit list --all --status\n",
    "```\n",
    "\n",
    "This will print out the names of all runnable tasks, and whether they have been (or need to be) run."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ffff2ed1-c568-4a6e-af22-91dc99d69cc8",
   "metadata": {},
   "source": [
    "### Inspect Tasks\n",
    "\n",
    "With the name of the task from `list`, you can learn more about a specific task.\n",
    "\n",
    "```bash\n",
    "doit info hello\n",
    "```\n",
    "\n",
    "This prints out more information about the task."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "30efbc61-f9c4-4835-bb8d-651ba829d11c",
   "metadata": {},
   "source": [
    "## Extend with `doitoml`\n",
    "\n",
    "Now that some tasks are running, `doitoml` provides some tools to help keep your task definitions short and reusable.\n",
    "\n",
    "| section | description |\n",
    "|-|-|\n",
    "| [`env`](#env) | environment variables\n",
    "| [`paths`](#paths) | reusable paths\n",
    "| [`tokens`](#tokens) | command shell tokens\n",
    "| [`templates`](../how-to/templates.md) | data-driven templates"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6a61a4f1-3350-40f7-8111-983a4b7588ee",
   "metadata": {},
   "source": [
    "### `paths`\n",
    "\n",
    "Paths are the most robust way to manage the relationships between tasks. `doitoml.paths` allow for defining paths which can be reused in multiple tasks."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32b01728-bfee-41f5-bb37-f50a7455bbf2",
   "metadata": {},
   "source": [
    "#### Simple paths\n",
    "\n",
    "The simplest path is just a list of strings, treated as relative paths to the file that defines them.\n",
    "\n",
    "```toml\n",
    "[tool.doitoml.paths]\n",
    "hello = [\"hello.txt\"]\n",
    "hola = [\"es/hola.txt\"]\n",
    "```\n",
    "\n",
    "> **Note**\n",
    ">\n",
    "> Only POSIX-style slashes `/` are supported as `\\` is used as an escape character by most syntaxes."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ea597d33-fee4-45a4-9423-5a9c5320ec91",
   "metadata": {},
   "source": [
    "#### Reusing paths\n",
    "\n",
    "Paths can be reused in _other_ paths, with the `::` syntax:\n",
    "\n",
    "```toml\n",
    "[tool.doitoml.paths]\n",
    "hello = [\"hello.py\"]\n",
    "greetings = [\"::hello\"]\n",
    "```\n",
    "\n",
    "And in _token_-type tasks:\n",
    "\n",
    "```toml\n",
    "[tool.doitoml.tasks.hello]\n",
    "actions = [[\"python\", \"::hello\"]]\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c79f7e1a-f825-478e-920a-1395fd60d772",
   "metadata": {
    "tags": []
   },
   "source": [
    "> **Note**\n",
    ">\n",
    "> A number of other [path patterns](../how-to/dsl.md) are available, and can also be [extended](../understanding/extending.md) with new syntax."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "97ddebcb-5f3a-4cf6-beba-e88ad4909017",
   "metadata": {},
   "source": [
    "#### Referencing `env`\n",
    "\n",
    "Paths can also reference environment variables.\n",
    "\n",
    "```toml\n",
    "[tool.doitoml.env]\n",
    "MY_NUMBER = \"42\"\n",
    "\n",
    "[tool.doitoml.paths]\n",
    "my_build = \"my-project-${MY_NUMBER}.zip\"\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a0739257-ba10-4d1f-819a-7ef9cce5fcbe",
   "metadata": {},
   "source": [
    "### `env`\n",
    "\n",
    "Environment variables are a cross-platform, cross-language way to provide consistent data across many processes.\n",
    "\n",
    "```toml\n",
    "[tool.doitoml.env]\n",
    "MY_DATA = \"some-data\"\n",
    "MY_OTHER_DATA = \"more-of-${MY_DATA}\"\n",
    "```\n",
    "\n",
    "> **Note**\n",
    ">\n",
    "> Only the POSIX-style `${ENV_VAR}` syntax is supported: `$ENV_VAR` and `%ENV_VAR%` have no particular meaning.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6c55c7fb-12b9-4ffc-b2c7-f6132a3b7ab3",
   "metadata": {},
   "source": [
    "### `tokens`\n",
    "\n",
    "The `tokens` section is useful for defining frequently-reused strings, and share the same namespace as `paths`.\n",
    "\n",
    "\n",
    "```toml\n",
    "[tool.doitoml.tokens]\n",
    "py = [\"python3\"]\n",
    "py_c = [\"::py\", \"-c\"]\n",
    "py_m = [\"::py\", \"-m\"]\n",
    "```\n",
    "\n",
    "These are useful for keeping task actions short.\n",
    "\n",
    "```toml\n",
    "[tool.doitoml.tasks.hello]\n",
    "actions = [[\"::py_c\", \"print('hello')\"]]\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ae133848-3b06-48dd-a38c-99875e70ac9e",
   "metadata": {},
   "source": [
    "### Summary\n",
    "\n",
    "Building declarative tasks for `doit` with `doitoml` makes it easier to automate simple, software-driven tasks in a predictable, reproducible way, but this barely scratches the surface of what is possible.\n",
    "\n",
    "\n",
    "> **Hint**\n",
    "> \n",
    "> For an overview, see the [cheatsheet](../reference/cheatsheet.md).\n",
    "\n",
    "\n",
    "Additionally, see more in-depth guides:\n",
    "\n",
    "> TODO\n",
    ">\n",
    "> - _Defining tasks in multiple files_\n",
    "> - _Extending `doitoml`_\n",
    "> - _Data-driven projects_"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}