Skip to content

Commit

Permalink
Small adjustments to the installation instructions (#50)
Browse files Browse the repository at this point in the history 
### What kind of change does this PR introduce?

* Small adjustments to the installation instructions.
* Fixed bad spacing that broke the numbering.

### Does this PR introduce a breaking change?


### Other information:
  • Loading branch information
@RondeauG
RondeauG authored Jun 14, 2024
2 parents 1df5564 + 65ecbe4 commit 7768d8b
Show file tree
Hide file tree
Showing 2 changed files with 119 additions and 31 deletions.
72 changes: 54 additions & 18 deletions {{cookiecutter.project_slug}}/CONTRIBUTING.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,53 +73,67 @@ Get Started!

Ready to contribute? Here's how to set up ``{{ cookiecutter.project_name }}`` for local development.

#. Fork the ``{{ cookiecutter.project_name }}`` repo on GitHub.
#. Clone your fork locally:
#. First, clone the ``{{ cookiecutter.project_name }}`` repo locally.

.. code-block:: console
* If you are not a ``{{ cookiecutter.project_name }}`` collaborator, first fork the ``{{ cookiecutter.project_name }}`` repo on GitHub, then clone your fork locally.

.. code-block:: console
git clone [email protected]:your_name_here/{{ cookiecutter.project_name | replace(' ', '-') }}.git
git clone [email protected]:your_name_here/{{ cookiecutter.project_name | replace(' ', '-') }}.git
* If you are a ``{{ cookiecutter.project_name }}`` collaborator, clone the ``{{ cookiecutter.project_name }}`` repo directly.

.. code-block:: console
git clone [email protected]:``{{ cookiecutter.github_username }}``/{{ cookiecutter.project_name | replace(' ', '-') }}.git
#. Install your local copy into a development environment. {% if cookiecutter.use_conda == 'y' -%}

You can create a new Anaconda development environment with:
You can create a new Anaconda development environment with:

.. code-block:: console
conda env create -f environment-dev.yml
conda activate {{ cookiecutter.project_slug }}
conda activate {{ cookiecutter.project_slug }}-dev
make dev
{%- else -%}
{%- else -%}

Using ``virtualenv`` (``virtualenvwrapper``), you can create a new development environment with:
Using ``virtualenv`` (``virtualenvwrapper``), you can create a new development environment with:

.. code-block:: console
python -m pip install virtualenvwrapper
mkvirtualenv {{ cookiecutter.project_slug }}
cd {{ cookiecutter.project_slug }}/
make dev
{%- endif %}
{%- endif %}

If you are on Windows, replace the ``make dev`` command with the following:

.. code-block:: console
python -m pip install -e .[dev]
pre-commit install
This installs ``{{ cookiecutter.project_slug }}`` in an "editable" state, meaning that changes to the code are immediately seen by the environment. To ensure a consistent coding style, `make dev` also installs the ``pre-commit`` hooks to your local clone.
This installs ``{{ cookiecutter.project_slug }}`` in an "editable" state, meaning that changes to the code are immediately seen by the environment. To ensure a consistent coding style, `make dev` also installs the ``pre-commit`` hooks to your local clone.

On commit, ``pre-commit`` will check that{% if cookiecutter.use_black == 'y' %} ``black``, ``blackdoc``, ``isort``,{% endif %} ``flake8``, and ``ruff`` checks are passing, perform automatic fixes if possible, and warn of violations that require intervention. If your commit fails the checks initially, simply fix the errors, re-add the files, and re-commit.
On commit, ``pre-commit`` will check that{% if cookiecutter.use_black == 'y' %} ``black``, ``blackdoc``, ``isort``,{% endif %} ``flake8``, and ``ruff`` checks are passing, perform automatic fixes if possible, and warn of violations that require intervention. If your commit fails the checks initially, simply fix the errors, re-add the files, and re-commit.

You can also run the hooks manually with:
You can also run the hooks manually with:

.. code-block:: console
pre-commit run -a
If you want to skip the ``pre-commit`` hooks temporarily, you can pass the `--no-verify` flag to `git commit`.
If you want to skip the ``pre-commit`` hooks temporarily, you can pass the `--no-verify` flag to `git commit`.

#. Create a branch for local development:

.. code-block:: console
git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
Now you can make your changes locally.

#. When you're done making changes, we **strongly** suggest running the tests in your environment or with the help of ``tox``:

Expand All @@ -138,7 +152,7 @@ Ready to contribute? Here's how to set up ``{{ cookiecutter.project_name }}`` fo
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature
If ``pre-commit`` hooks fail, try re-committing your changes (or, if need be, you can skip them with `git commit --no-verify`).
If ``pre-commit`` hooks fail, try fixing the issues, re-staging the files to be committed, and re-committing your changes (or, if need be, you can skip them with `git commit --no-verify`).

#. Submit a `Pull Request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`_ through the GitHub website.

Expand All @@ -154,13 +168,33 @@ Ready to contribute? Here's how to set up ``{{ cookiecutter.project_name }}`` fo
# To simply test that the docs pass build checks
python -m tox -e docs
#. If changes to your branch are made on GitHub, you can update your local branch with:

.. code-block:: console
git checkout name-of-your-bugfix-or-feature
git fetch
git pull origin name-of-your-bugfix-or-feature
If you have merge conflicts, you might need to replace `git pull` with `git merge` and resolve the conflicts manually.
Resolving conflicts from the command line can be tricky. If you are not comfortable with this, you can ignore the last command and instead use a GUI like PyCharm or Visual Studio Code to merge the remote changes and resolve the conflicts.

#. Before merging, your Pull Request will need to be based on the `main` branch of the ``{{ cookiecutter.project_name }}`` repository. If your branch is not up-to-date with the `main` branch, you can perform similar steps as above to update your branch:

.. code-block:: console
git checkout name-of-your-bugfix-or-feature
git fetch
git pull origin main
See the previous step for more information on resolving conflicts.

#. Once your Pull Request has been accepted and merged to the `main` branch, several automated workflows will be triggered:

- The ``bump-version.yml`` workflow will automatically bump the patch version when pull requests are pushed to the `main` branch on GitHub. **It is not recommended to manually bump the version in your branch when merging (non-release) pull requests (this will cause the version to be bumped twice).**
- `ReadTheDocs` will automatically build the documentation and publish it to the `latest` branch of `{{ cookiecutter.project_slug }}` documentation website.
- If your branch is not a fork (ie: you are a maintainer), your branch will be automatically deleted.

You will have contributed your first changes to ``{{ cookiecutter.project_slug }}``!
You will have contributed to ``{{ cookiecutter.project_slug }}``!

Pull Request Guidelines
-----------------------
Expand All @@ -169,9 +203,11 @@ Before you submit a pull request, check that it meets these guidelines:

#. The pull request should include tests and should aim to provide `code coverage <https://en.wikipedia.org/wiki/Code_coverage>`_ for all new lines of code. You can use the `--cov-report html --cov {{ cookiecutter.project_slug }}` flags during the call to ``pytest`` to generate an HTML report and analyse the current test coverage.

#. If the pull request adds functionality, the docs should also be updated. Put your new functionality into a function with a docstring, and add the feature to the list in ``README.rst``.
#. All functions should be documented with `docstrings` following the `numpydoc <https://numpydoc.readthedocs.io/en/latest/format.html>`_ format.

#. If the pull request adds functionality, either update the documentation or create a new notebook that demonstrates the feature. Library-defining features should also be listed in ``README.rst``.

#. The pull request should work for Python 3.8, 3.9, 3.10, 3.11, 3.12 and PyPy. Check that the tests pass for all supported Python versions.
#. The pull request should work for all currently supported Python versions. Check the `pyproject.toml` or `tox.ini` files for the list of supported versions.

Tips
----
Expand Down
78 changes: 65 additions & 13 deletions {{cookiecutter.project_slug}}/docs/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,19 @@
Installation
============

..
We strongly recommend installing {{ cookiecutter.project_name }}, in an Anaconda Python environment. Futhermore, due to the complexity of some packages, the default dependency solver can take a long time to resolve the environment. If `mamba` is not already your default solver, consider running the following commands in order to speed up the process:
.. code-block:: console
conda install -n base conda-libmamba-solver
conda config --set solver libmamba
If you don't have `pip`_ installed, this `Python installation guide`_ can guide you through the process.

.. _pip: https://pip.pypa.io
.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/

Stable release
--------------

Expand All @@ -11,33 +24,72 @@ To install {{ cookiecutter.project_name }}, run this command in your terminal:
python -m pip install {{ cookiecutter.project_slug }}
This is the preferred method to install {{ cookiecutter.project_name }}, as it will always install the most recent stable release.
..
.. code-block:: console
If you don't have `pip`_ installed, this `Python installation guide`_ can guide you through the process.
conda install {{ cookiecutter.project_slug }}

.. _pip: https://pip.pypa.io
.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
This is the preferred method to install {{ cookiecutter.project_name }}, as it will always install the most recent stable release.


From sources
------------

The sources for {{ cookiecutter.project_name }} can be downloaded from the `Github repo <{{ cookiecutter.__gh_slug}}>`_.

You can either clone the public repository:
#. Download the source code from the `Github repo`_ using one of the following methods:

.. code-block:: console
* Clone the public repository:

git clone [email protected]:{{ cookiecutter.github_username }}/{{ cookiecutter.project_name | replace(' ', '_') }}.git
.. code-block:: console
Or download the `tarball <{{ cookiecutter.__gh_slug}}/tarball/main>`_:
git clone [email protected]:{{ cookiecutter.github_username }}/{{ cookiecutter.project_name | replace(' ', '_') }}.git
.. code-block:: console
* Download the `tarball <{{ cookiecutter.__gh_slug}}/tarball/main>`_:

curl -OJL {{ cookiecutter.__gh_slug}}/tarball/main
.. code-block:: console
Once you have a copy of the source, you can install it with:
curl -OJL {{ cookiecutter.__gh_slug}}/tarball/main
.. code-block:: console
#. Once you have a copy of the source, you can install it with:

.. code-block:: console
python -m pip install .
..
.. code-block:: console
conda env create -f environment-dev.yml
conda activate {{ cookiecutter.project_slug }}-dev
make dev

If you are on Windows, replace the ``make dev`` command with the following:

.. code-block:: console
python -m pip install -e .[dev]
Even if you do not intend to contribute to `{{ cookiecutter.project_name }}`, we favor using `environment-dev.yml` over `environment.yml` because it includes additional packages that are used to run all the examples provided in the documentation.
If for some reason you wish to install the `PyPI` version of `{{ cookiecutter.project_name }}` into an existing Anaconda environment (*not recommended if requirements are not met*), only run the last command above.

#. When new changes are made to the `Github repo`_, if using a clone, you can update your local copy using the following commands from the root of the repository:

.. code-block:: console
git fetch
git checkout main
git pull origin main
python -m pip install .
..
.. code-block:: console
git fetch
git checkout main
git pull origin main
conda env update -n {{ cookiecutter.project_slug }}-dev -f environment-dev.yml
conda activate {{ cookiecutter.project_slug }}-dev
make dev

python -m pip install .
These commands should work most of the time, but if big changes are made to the repository, you might need to remove the environment and create it again.

0 comments on commit 7768d8b

Please sign in to comment.