DGAFCLI.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# dgaf cli\n",
    "\n",
    "`dgaf` is a project automation system built around a `pyproject.toml`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting Started\n",
    "\n",
    "`dgaf` can get started based on what you already have, like:\n",
    "- version control\n",
    "- binder/[repo2docker](https://repo2docker.readthedocs.io/en/latest/) definition\n",
    "- `README.md`\n",
    "- `CONTRIBUTING.md`\n",
    "- github/azure/travis actions\n",
    "\n",
    "\n",
    "```bash\n",
    "$> dgaf init -f\n",
    "\n",
    "[dgaf]            starting a new project in ~/foobar\n",
    "[.git]            no .git found, initialize? [y]n  y    \n",
    "\n",
    "    $> git init\n",
    "    Initialized empty Git repository in ~/foobar/.git/\n",
    "\n",
    "[README.md]       found, extract data from content? [y]n  y\n",
    "[pyproject.toml]  not found\n",
    "[pyproject.toml]  creating boilerplate... pep.517\n",
    "```\n",
    "```toml\n",
    "    [build-system]\n",
    "    requires = [\"setuptools>=40.8.0\", \"wheel\"]\n",
    "    build-backend = \"setuptools.build_meta:__legacy__\"\n",
    "    \n",
    "    [tools.dgaf]\n",
    "    $schema = \"https://deathbeds.github.io/dgaf#0.1.0\"\n",
    "```\n",
    "\n",
    "```bash\n",
    "[pyproject.toml]  created\n",
    "[.git]            committing\n",
    "    \n",
    "    $> git add pyproject.toml README.md && git commit -m \"initialized project with [dgaf] 0.1.0 :tada:\"\n",
    "    \n",
    "    [master (root-commit) d41ebf3] initialized project with [dgaf] 0.1.0 🎉\n",
    "    1 file changed, 8 insertions(+)\n",
    "    create mode 100644 README.md\n",
    "    create mode 100644 pyproject.toml\n",
    "\n",
    "[dgaf]            new actions learned\n",
    "\n",
    "    $> dgaf commit [files]        commit some files\n",
    "    $> dgaf fetch                 fetch some files\n",
    "    $> dgaf branch                make a branch\n",
    "\n",
    "    Next you might want to try out some features. List them all with `dgaf add<tab>`\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding Features and Providers\n",
    "\n",
    "```bash\n",
    "$> dgaf add flit\n",
    "\n",
    "[dgaf]               adding flit\n",
    "[pyproject.toml]     found, uses:               pep517 (default)\n",
    "[flit]               provides:                  pep517 (flit)\n",
    "[pep517 (flit)]      updating pyproject.toml\n",
    "```\n",
    "```toml\n",
    "    [build-system]                                          [build-system]\n",
    "    requires = [\"setuptools>=40.8.0\", \"wheel\"]              requires = [\"flit_core >=2,<4\"]\n",
    "    build-backend = \"setuptools.build_meta:__legacy__\"      build-backend = \"flit_core.buildapi\"\n",
    "\n",
    "                                                            [tool.flit.metadata]\n",
    "                                                            module = \"foobar\"\n",
    "```\n",
    "```bash\n",
    "[.git]              committing\n",
    "\n",
    "    $> git add pyproject.toml README.md && git commit -m \"added [flit] with [dgaf]\"\n",
    "    \n",
    "    [master 08b94a2] added [flit] with [dgaf] :butterfly:\n",
    "    1 file changed, 6 insertions(+), 4 deletions(-)\n",
    "\n",
    "[dgaf]              new actions learned\n",
    "    \n",
    "    dgaf build[:flit]    create redistributable python artifacts\n",
    "    dgaf publish[:flit]  upload artifacts\n",
    "    dgaf install[:flit]  install into the current working enviroment\n",
    "    dgaf flit            run flit commands\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Actions\n",
    "\n",
    "```bash\n",
    "$> dgaf add doit\n",
    "[dgaf]                 adding doit\n",
    "[pyproject.toml]       found, uses: pep517\n",
    "[pyproject.toml]       initializing tasks\n",
    "```\n",
    "\n",
    "```toml\n",
    "    [tools.dgaf.add.doit]\n",
    "    auto = true\n",
    "    \n",
    "    [tools.dgaf.doit.paths]\n",
    "    pyproject = \"pyproject.toml\"\n",
    "    wheel = \"dist/{{ project.name }}-{{ project.version }}.whl\"\n",
    "    sdist = \"dist/{{ project.name }}-{{ project.version }}.tar.gz\"\n",
    "    \n",
    "    [tools.dgaf.doit.data]\n",
    "    pyproject = {\"toml\": \"pyproject.toml\"}\n",
    "    \n",
    "    [tools.dgaf.doit.tasks.build]\n",
    "    uptodate = [\n",
    "       {\"doit.tools.config_changed\": {\"jmsespath\": [\"pyproject\", \"/foo/bar\"]}}\n",
    "    ]\n",
    "    targets = [\"{{ wheel }}\", \"{{ sdist }}\"]\n",
    "    actions = [\"flit\", \"build\"]\n",
    "```\n",
    "\n",
    "```bash\n",
    "[dodo.py]              not found, initializing\n",
    "```\n",
    "\n",
    "```python\n",
    "    def task_dgaf():\n",
    "        import pathlib, toml, dgaf.tools.doit\n",
    "        pyproj = toml.loads(pathlib.Path(\"pyproject.toml\").read_text())\n",
    "        for name, task in pyproj[\"tools\"][\"dgaf\"][\"doit\"][\"tasks\"].items():\n",
    "            yield dgaf.tools.doit.yield_task(name, task)\n",
    "\n",
    "[dgaf]              new actions learned\n",
    "    \n",
    "    dgaf build[:doit]    run the build with doit\n",
    "    dgaf doit            run any doit task\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Start an interactive session\n",
    "```bash\n",
    "$> dgaf\n",
    "\n",
    "# dgaf v0.1.0 - Python 3.9.0\n",
    "       In[1]: doit publish\n",
    "\n",
    "      Out[1]: └──[■□□□□□□□□□ doit:publish]\n",
    "                 ├──[■■■■■■□□□□ doit:lint]\n",
    "                 └──[□□□□□□□□□□ doit:build]\n",
    "\n",
    "       In[ ]: \n",
    "```\n",
    "\n",
    "- all top-level CLI commands also exist here\n",
    "- all data (e.g. `pyproject.toml`) is available"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Start a web session\n",
    "\n",
    "```bash\n",
    "$> dgaf lab\n",
    "\n",
    "\n",
    "# dgaf v0.1.0 - Python 3.9.0 - JupyterLab 3.0.0rc5               # serving :⬤. on http://localhost:8888/lab/workspaces/dgaf?token=abcedf\n",
    "\n",
    "    In[]:\n",
    "```\n",
    "\n",
    "- start a JupyterLab in-loop\n",
    "- launches a workspace inside a running `dgaf` console kernel\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Upgrading\n",
    "\n",
    "After upgrading `dgaf` (or a plugin), you might see:\n",
    "\n",
    "```\n",
    "[dgaf]   new migrations for: [flit] [doit] [robot]\n",
    "```\n",
    "```markdown\n",
    "> start `dgaf migrate` to learn more\n",
    "```\n",
    "\n",
    "```bash\n",
    "$> dgaf migrate\n",
    "[dgaf]      new migrations available\n",
    "\n",
    "    $> dgaf migrate flit [2020.10.18]\n",
    "    \n",
    "        adds some new metadata fields\n",
    "    \n",
    "    $> dgaf migrate doit [2020.10.19]\n",
    "        \n",
    "        upgrades doit version, removes pyproject.toml hack\n",
    "\n",
    "    $> dgaf migrate robot [2020.10.19]\n",
    "        \n",
    "        adds robotframework output improvements\n",
    "```\n",
    "\n",
    "- running migrations create intermediate commits, so they can be rolled back\n",
    "  - optionally, each set of migrations can trigger tasks, e.g. `test`"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.8.6"
  },
  "toc-autonumbering": true
 },
 "nbformat": 4,
 "nbformat_minor": 4
}