{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "781428cc",
   "metadata": {},
   "source": [
    "# Preliminaries: Once and for All"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fe27412c",
   "metadata": {},
   "source": [
    "## Install a Python Distribution if You Don't Have One Already"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4e2464da",
   "metadata": {},
   "source": [
    "Ensure that the following requirements are made:\n",
    "\n",
    "- The Python distribution is recent enough. As a rule of thumb, you should aim to keep one of the last three stable distributions at all times, e.g. 3.10, 3.11, 3.12 if 3.12 is the last stable (non-beta) release.\n",
    "- The package manager [PIP](https://pip.pypa.io/en/stable/) is included."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4ae10347",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-10-18T08:20:26.157990Z",
     "start_time": "2023-10-18T08:20:26.135641Z"
    }
   },
   "source": [
    "## Create Accounts on the Websites"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "85a253b3",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-10-18T08:20:26.157990Z",
     "start_time": "2023-10-18T08:20:26.135641Z"
    }
   },
   "source": [
    "Ensure that you have accounts (preferably with the same login) on:\n",
    "\n",
    "- [GitHub](https://github.com/),\n",
    "- [PyPI](https://pypi.org/).\n",
    "\n",
    "PyPi:\n",
    "\n",
    "- Go to \"Your account\" → \"Account Settings\" → \"API tokens\" → \"Add API token\".\n",
    "- \"Token name\" → github (for example).\n",
    "- \"Scope\" → \"Entire account (all projects)\".\n",
    "- Click on \"create token\". Keep it somewhere safe.\n",
    "\n",
    "You will need access to [Codecov](https://app.codecov.io/gh/), but you can login with your GitHub account.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0907cf9e",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-10-18T08:20:26.157990Z",
     "start_time": "2023-10-18T08:20:26.135641Z"
    }
   },
   "source": [
    "## Install Git"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "73fa7150",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-10-18T08:20:26.157990Z",
     "start_time": "2023-10-18T08:20:26.135641Z"
    }
   },
   "source": [
    "*Git will be used to maintain your projects branches locally and remotely.*\n",
    "\n",
    "Install git: https://git-scm.com/downloads. You may need to restart your computer.\n",
    "\n",
    "Test it:\n",
    "\n",
    "```console\n",
    "$ git --version\n",
    "```\n",
    "\n",
    "Ensure your version is recent enough (>=2.40).\n",
    "\n",
    "\n",
    "Recommended: enter the following command.\n",
    "\n",
    "```console\n",
    "$ git config --add remote.origin.fetch '^refs/heads/gh-pages'\n",
    "```\n",
    "\n",
    "The command above tells `git` to ignore the branch `gh-pages`. `gh-pages` is the remote branch that hosts your compiled documentation. By default, git will store locally all versions of your documentation, which can take a lot of place for nothing. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "94a162c6",
   "metadata": {},
   "source": [
    "## Install Pandoc"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f88ab013",
   "metadata": {},
   "source": [
    "PH3 gives you the possibility to insert Jupyter Notebooks in your documentation. This requires the installation of the Pandoc converter: https://pandoc.org/installing.html"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6cacf8bc",
   "metadata": {},
   "source": [
    "## Install Poetry"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6f2301c9",
   "metadata": {},
   "source": [
    "[Poetry](https://python-poetry.org/) will handle all the issues related to package management (dependencies, versioning, deployment) for you.\n",
    "\n",
    "To install it, please follow the instructions from https://python-poetry.org/docs/#installation\n",
    "\n",
    "Check that it works:\n",
    "\n",
    "```console\n",
    "$ poetry --version\n",
    "```\n",
    "\n",
    "Additionally the following commands are recommended:\n",
    "\n",
    "```console\n",
    "$ poetry config virtualenvs.in-project true\n",
    "$ poetry self add poetry-bumpversion\n",
    "$ poetry self add poetry-plugin-up\n",
    "```\n",
    "\n",
    "As one can guess, the first command tells that the virtual environment (venv) of a project should be created inside the project instead of within a centralized directory. It facilitates keeping track of the matchings between projects and venvs.\n",
    "\n",
    "The second command installs a poetry plugin that facilitates the management of the version number of your package.\n",
    "\n",
    "The last one installs a poetry plugin to automatically update dependencies and bump their versions in the `pyproject.toml` file. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6aaa2187",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-10-18T08:20:26.157990Z",
     "start_time": "2023-10-18T08:20:26.135641Z"
    }
   },
   "source": [
    "## Install Package Helper 3"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e00e5df4",
   "metadata": {},
   "source": [
    "In a terminal (Anaconda Prompt, Bash, Windows Powershell, etc):"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c4de97e4",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-10-18T08:20:26.157990Z",
     "start_time": "2023-10-18T08:20:26.135641Z"
    }
   },
   "source": [
    "```console\n",
    "$ pip install package-helper-3\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "adc38451",
   "metadata": {},
   "source": [
    "Check that the installation is correct:\n",
    "\n",
    "```console\n",
    "$ ph3 --help\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c1fdbdc1",
   "metadata": {},
   "source": [
    "## Install PyCharm"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3ec40c3a",
   "metadata": {},
   "source": [
    "Install using the binaries available here: https://www.jetbrains.com/pycharm/download/."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "586d7443",
   "metadata": {},
   "source": [
    "### Link PyCharm to your GitHub account"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "04b07de7",
   "metadata": {},
   "source": [
    "In PyCharm settings: Version Control → GitHub → Add account.\n",
    "\n",
    "Two options are available:\n",
    "\n",
    "- Log In with Token seems to be the recommended way. The first time, click on the generate button to open a GitHub page that will create an access token. Copy the token and paste it in PyCharm. PyCharm should remind it but to avoid generating a new token every other week you should keep a copy somewhere else as well (in a very safe place!).  \n",
    "- (deprecated) Log In via GitHub will open a GitHub page to grant you access."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2f4607c4",
   "metadata": {},
   "source": [
    "### [recommended] Change the documentation style"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ca27be84",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-10-18T08:20:26.157990Z",
     "start_time": "2023-10-18T08:20:26.135641Z"
    }
   },
   "source": [
    "We recommend the [Numpy documentation style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html).\n",
    "\n",
    "In PyCharm settings: Tools → Python Integrated Tools → Docstrings → Docstring format → NumPy."
   ]
  }
 ],
 "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.4"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}