diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 5367ecb30..ccd77f838 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -2,6 +2,9 @@ Contribution guide ================== Thank you for considering to contribute to Kernel Tuner! +.. role:: bash(code) + :language: bash + Reporting Issues ---------------- Not all contributions are code, creating an issue also helps us to improve. When you create an issue about a problem, please ensure the following: @@ -11,6 +14,30 @@ Not all contributions are code, creating an issue also helps us to improve. When * Describe what actually happened, including the output of any errors printed. * List the version of Python, CUDA or OpenCL, and C compiler, if applicable. +Development environment +----------------------- +The following steps help you set up a minimal development environment. This is just a suggestion, and can be done in many other ways. + +Steps with :bash:`sudo` access: + +#. Clone the git repository to the desired location +#. Install `pyenv `__: :bash:`curl https://pyenv.run | bash` (remember to add the output to :bash:`.bash_profile` and :bash:`.bashrc` as specified) + * [Optional] setup a local virtual environment in the folder: pyenv virtualenv [virtualenv-name] +#. Install the required Python versions: :bash:`pyenv install 3.8 3.9 3.10 3.11` +#. Set the Python versions so they can be found: :bash:`pyenv global 3.8 3.10 3.11` (replace :bash:`global` with :bash:`local` when using the virtualenv) +#. Install Nox: :bash:`pip install nox` + +Steps without :bash:`sudo` access (e.g. on a cluster): + +#. Clone the git repository to the desired location +#. Install Conda with `Mamba `__ (for better performance) or `Miniconda `__ (for traditional minimal Conda). + * [Optional] both Mamba and Miniconda can be automatically activated via :bash:`~/.bashrc`. Do not forget to add these (usually mentioned at the end of the installation). +#. Setup a Conda virtual environment for each of the required Python versions: :bash:`conda create --name python3.x python=3.x`. Verify the environments are setup with `conda info --envs`. +#. Install Nox: :bash:`pip install nox` +#. Set Nox to use the correct backend: + * If you used Mamba in step 2: :bash:`nox --default-venv-backend mamba` + * If you used Miniconda or Anaconda in step 2: :bash:`nox --default-venv-backend conda` + Contributing Code ----------------- For contributing code to Kernel Tuner please select an issue to work on or create a new issue to propose a change or addition. For significant changes, it is required to first create an issue and discuss the proposed changes. Then fork the repository, create a branch, one per change or addition, and create a pull request. @@ -19,9 +46,9 @@ Kernel Tuner follows the Google Python style guide, with Sphinxdoc docstrings fo Before creating a pull request please ensure the following: -* You have written unit tests to test your additions and all unit tests pass (run `nox`) +* You have written unit tests to test your additions and all unit tests pass (run :bash:`nox`). If you do not have the required hardware, you can run :bash:`nox -- skip-gpu`, or :bash:`skip-cuda`, :bash:`skip-hip`, :bash:`skip-opencl`. * The examples still work and produce the same (or better) results -* An entry about the change or addition is created in CHANGELOG.md +* An entry about the change or addition is created in :bash:`CHANGELOG.md` * Any matching entries in the roadmap.md are updated/removed If you are in doubt on where to put your additions to the Kernel Tuner, please @@ -38,16 +65,16 @@ Afer cloning, you can install the packages required to run the tests using: pip install -e . After this command you should be able to run the tests and build the documentation. -See below on how to do that. The ``-e`` flag installs the package in *development mode*. +See below on how to do that. The :bash:`-e` flag installs the package in *development mode*. This means files are not copied, but linked to, such that your installation tracks changes in the source files. -Additionally you can install any of the optional runtime dependencies by appending e.g. `--extras cuda,opencl` to the Poetry command. -If you want to go all-out, use `--all-extras`. +Additionally you can install any of the optional runtime dependencies by appending e.g. :bash:`-E cuda`, `-E opencl` to the Poetry command. +If you want to go all-out, use :bash:`--all-extras`. Running tests ------------- -To run the tests you can use ``pytest`` (to run against the local Python version) and ``nox``` (to run against all supported Python versions) in the top-level directory. +To run the tests you can use :bash:`pytest` (to run against the local Python version) and :bash:`nox` (to run against all supported Python versions) in the top-level directory. Note that tests that require PyCuda and/or a CUDA capable GPU will be skipped if these are not installed/present. The same holds for tests that require PyOpenCL, Cupy, Nvidia CUDA. diff --git a/INSTALL.rst b/INSTALL.rst index b32fc675a..3bc18c6b2 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -159,12 +159,12 @@ The runtime dependencies are: - `hip`: install pyhip along with kernel_tuner - `tutorial`: install packages required to run the guides -These can be installed by appending e.g. ``--extras cuda,opencl``. +These can be installed by appending e.g. ``-E cuda -E opencl``. If you want to go all-out, use ``--all-extras``. For example, use: ``` -pip install --with test,docs --extras cuda,opencl +pip install --with test,docs -E cuda -E opencl ``` To install Kernel Tuner along with all the packages required for development. diff --git a/doc/source/docutils.conf b/doc/source/docutils.conf new file mode 100644 index 000000000..1bf4d8323 --- /dev/null +++ b/doc/source/docutils.conf @@ -0,0 +1,2 @@ +[restructuredtext parser] +syntax_highlight = short