.. _contribute_dynalib:

Contribute
==========

Overall guidance on contributing to a PyAnsys library appears in the
`Contributing <dev_guide_contributing_>`_ topic in the *PyAnsys developer's guide*.
Ensure that you are thoroughly familiar with this guide before attempting to contribute
to DYNA-Lib.

The following contribution information is specific to DYNA-Lib.

Developer installation
----------------------
Installing the ``dynalib`` package in developer mode allows you to modify the source and
enhance it.

This package supports Python 3.9 through 3.12 on Windows, Linux, and MacOS.

You can install the ``dynalib`` package with this command:

.. code::

   pip install dynalib

Alternatively, you can install the latest version from the `DYNA-Lib repository
<dynalib_repo_>`_ with this command:

.. code::

   pip install git+https://github.com/ansys/dynalib

For a local development version, you can create a new `virtual environment <venv_>`_
with this command:

.. code:: bash

    python -m venv .venv

You can then activate the virtual environment with the command appropriate for your operating system.

**On Windows:**

.. code::

   D.\.venv\Scripts\activate
  
**On Linux and MacOS:**
  
.. code::

   source .venv/bin/activate
  
Next, install the development version of the project with these commands:

.. code::

   git clone https://github.com/ansys/dynalib
   cd dynalib
   pip install -e .

Testing
-------
Once DYNA-Lib is installed in developer mode, you can install testing
requirements and use `pytest`_ to run unit tests with these commands:

.. code::

   pip install .[test]
   pytest


Documentation
-------------
To install the required dependencies for the documentation, run this command:

.. code::

    pip install .[doc]


To build the documentation, run the usual rules provided in the `Sphinx <Sphinx_>`_
Makefile for your operating system.

**On Windows:**

.. code::

   .\doc\make.bat html
   .\doc\build\html\index.html

**On Linux and MacOS:**

.. code::

   make -C doc/ html && your_browser_name doc/build/html/index.html

Post issues
-----------
Use the `DYNA-Lib Issues <dynalib_repo_issues_>`_ page to create issues to
report bugs and request new features.. When possible, use these issue
templates:

* Bug report template
* Feature request template
* Documentation issue template
* Example request template

If your issue does not fit into one of these categories, create your own issue.

To reach the PyAnsys support team, email `pyansys.core@ansys.com <pyansys.core@ansys.com>`_.

Testing
-------
You can install the dependencies required for testing with this command:

.. code:: bash

    pip install .[tests]

You can then run the tests via ``pytest`` with this command:

.. code:: bash

    pytest -v


Adhere to code style
--------------------
DYNA-Lib follows the PEP8 standard as indicated in `PEP 8 <dev_guide_pyansys_pep8_>`_
in the *PyAnsys developer's guide* and implements style checking using `pre-commit <pre-commit_>`_.

To ensure your code meets minimum code styling standards, run these commands:

.. code:: console

  pip install pre-commit
  pre-commit run --all-files

You can also install this as a pre-commit hook by running this command:

.. code:: console

  pre-commit install

This way, it's not possible for you to push code that fails the style checks:

.. code:: text

  $ git commit -am "added my cool feature"
  black....................................................................Passed
  blacken-docs.............................................................Passed
  isort....................................................................Passed
  flake8...................................................................Passed
  docformatter.............................................................Passed
  codespell................................................................Passed
  check for merge conflicts................................................Passed
  debug statements (python)................................................Passed
  check yaml...............................................................Passed
  trim trailing whitespace.................................................Passed
  Add License Headers......................................................Passed
  Validate GitHub Workflows................................................Passed

.. LINKS AND REFERENCES
.. _dev_guide_contributing: https://dev.docs.pyansys.com/how-to/contributing.html
.. _dynalib_repo: https://github.com/ansys/dynalib
.. _venv: https://docs.python.org/3/library/venv.html
.. _pytest: https://docs.pytest.org/en/stable/
.. _Sphinx: https://www.sphinx-doc.org/en/master/
.. _dynalib_repo_issues: https://github.com/ansys/dynalib/issues
.. _dev_guide_pyansys_pep8: https://dev.docs.pyansys.com/coding-style/pep8.html
.. _pre-commit: https://pre-commit.com/