diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst index 3c0aee46..9de8d671 100644 --- a/docs/getting-started/index.rst +++ b/docs/getting-started/index.rst @@ -10,4 +10,4 @@ If you are a new user or developer you find instructions here for how to get sta installation test-examples configuration - contribute + contribute <../notebooks/developper_install_instructions> diff --git a/docs/notebooks/developper_install_instructions.ipynb b/docs/notebooks/developper_install_instructions.ipynb new file mode 100644 index 00000000..67cdf699 --- /dev/null +++ b/docs/notebooks/developper_install_instructions.ipynb @@ -0,0 +1,168 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "29636569", + "metadata": {}, + "source": [ + "# developper installation instructions\n", + "\n", + "## prepare \n", + "cd work_dir\n", + "\n", + "deactivate existing python venv\n", + "\n", + "preconditions: \n", + "verify python version > 3.11 \n", + "verify github keys, or follow link to set them up \n", + "\n", + "## clone repositories for local development\n", + "```bash\n", + "git clone https://github.com/python-accelerator-middle-layer/tango-pyaml.git \n", + "git clone https://github.com/python-accelerator-middle-layer/pyaml.git \n", + "git clone https://github.com/python-accelerator-middle-layer/pyaml-cs-oa.git # optional\n", + "```\n", + "\n", + "## create virtual environment\n", + "python -m venv pyaml_venv \n", + "source ./pyaml_venv/bin/activate \n", + "pip install --upgrade pip \n", + "\n", + "## use latest pyAML version rather than latest release\n", + "```bash\n", + "cd pyaml \n", + "git submodule update --init --recursive \n", + "pip install -e . \n", + "cd .. \n", + "```\n", + "\n", + "## install tango-pyaml \n", + "\n", + "notice: do not do \"pip install -e .\" it does not work\n", + "\n", + "```bash\n", + "cd tango-pyaml \n", + "pip install . \n", + "cd .. \n", + "```\n", + "\n", + "[//]: # (OR latest ophid asych) \n", + "[//]: # (cd ../pyaml-cs-oa/ )\n", + "[//]: # (pip install -e . )\n", + "[//]: # (pip install -e .[dev] (very very long ~10 min on Simone's laptop) )\n", + "[//]: # (pre-commit install )\n", + "\n", + "## install dummy tango control system\n", + "\n", + "this will emulate device as in tango, but will not modify any beam dynamics value. only read/write of device attribute will be updated. read-only values will all return zero.\n", + "\n", + "```bash\n", + "cd pyaml\n", + "pip install ./tests/dummy_cs/tango-pyaml\n", + "cd ..\n", + "```\n", + "\n", + "## install virtual accelerator \n", + "SOLEIL will provide virtual accelerator installation scenario\n", + "\n", + "\n", + "## expected output\n", + "The output of pip list should be similar to: \n", + "```bash\n", + "accelerator-middle-layer 0.1.1 /Users/liuzzo/Desktop/test installation/pyaml \n", + "accelerator-toolbox 0.7.1 \n", + "annotated-types 0.7.0 \n", + "contourpy 1.3.3 \n", + "cycler 0.12.1 \n", + "docstring_parser 0.17.0 \n", + "fonttools 4.61.1 \n", + "h5py 3.15.1 \n", + "kiwisolver 1.4.9 \n", + "matplotlib 3.10.8 \n", + "numpy 2.3.5 \n", + "packaging 25.0 \n", + "pillow 12.0.0 \n", + "pip 25.3 \n", + "psutil 7.1.3 \n", + "pydantic 2.12.5 \n", + "pydantic_core 2.41.5 \n", + "pyparsing 3.2.5 \n", + "pytango 10.1.1 \n", + "python-dateutil 2.9.0.post0 \n", + "PyYAML 6.0.3 \n", + "scipy 1.16.3 \n", + "six 1.17.0 \n", + "tango-pyaml 0.3.1 \n", + "typing_extensions 4.15.0 \n", + "typing-inspection 0.4.2 \n", + "```\n", + "\n", + "## test that the installation is working correctly by running a pyAML example script\n", + "```bash\n", + "python ./pyaml/examples/ESRF_tune_example/esrf_tune_example.py \n", + "```\n", + "\n", + "## look at documentation to further test existing features\n", + "https://pyaml.readthedocs.io/en/latest/?badge=latest \n", + "\n", + "## example of development of pyaml documentation \n", + "```bash\n", + "cd pyaml\n", + "```\n", + "## create a new branch\n", + "```bash\n", + "git checkout -b doc-devnotebook\n", + "```\n", + "\n", + "## push the branch to remote\n", + "```bash\n", + "git push -u origin doc-devnotebook\n", + "```\n", + "\n", + "## modify something or add a file\n", + "```bash\n", + "edit ./pyaml/docs/notebooks/developper_install_instructions.ipynb \n", + "save\n", + "```\n", + "\n", + "## add file to git revision \n", + "```bash\n", + "git add docs/notebooks/developper_install_instructions.ipynb \n", + "```\n", + "\n", + "## test your code developments locally (in this example, build teh documentation locally)\n", + "```bash\n", + "pip install sphinx \n", + "pip install myst_nb \n", + "pip install pydata_sphinx_theme \n", + "python -m sphinx -b html docs ./docs/_build -d ./docs/_build \n", + "```\n", + "\n", + "## commit change\n", + "```bash\n", + "git commit ./docs/notebooks/developper_install_instructions.ipynb -m'some draft notes'\n", + "```\n", + "## push to remote\n", + "```bash\n", + "git push\n", + "```\n", + "### open a pull request to accept your change:\n", + "in a browser navigate to: https://github.com/python-accelerator-middle-layer/pyaml \n", + "click on \"compare and pull request\" \n", + "Add some description and click on Create pull request. \n", + "\n", + "The pull request page will open \n", + "Add reviewers to your pull request: in order to be approved, 2 positive reviews are needed. \n", + "\n", + "\n" + ] + } + ], + "metadata": { + "language_info": { + "name": "python" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}