Contribute#

Overall guidance on contributing to a PyAnsys library appears in the Contributing topic in the PyAnsys Developer’s Guide. Ensure that you are thoroughly familiar with this guide before attempting to contribute to PyConverter-XML2Py.

The following contribution information is specific to PyConverter-XML2Py.

Developer installation#

Follow these steps to install the package in developer mode:

  1. Clone the repository:

    git clone https://github.com/ansys/pyconverter-xml2py.git

  2. Create a fresh-clean Python environment and activate it. If you require additional information on creation of a virtual environment, see the official Python venv documentation.

    python -m venv .venv
source .venv/bin/activate

    python -m venv .venv
source .venv/bin/activate

    python -m venv .venv
.\.venv\Scripts\activate

  3. Make sure you have the latest version of pip:

    python -m pip install -U pip

  4. Install the project in editable mode:

    python -m pip install -e .

  5. Install additional requirements (if needed):

    python -m pip install .[doc,tests]

  6. Verify your development installation:

    pytest tests -v

Style and testing#

If required, you can call style commands (such as black, isort, and flake8) or unit testing commands (such as pytest) from the command line. However, this does not guarantee that your project is being tested in an isolated environment, which is why you might consider using tox.

Documentation#

For building documentation, you can run the usual rules provided in the Sphinx Makefile or make.bat:

python -m pip install .[doc]
make -C doc html

python -m pip install .[doc]
.\doc\make.bat html

Once the documentation is built, you can open it as follows.

By running the command:

your_browser_name doc/html/index.html

By opening the documentation, which you do by going to the doc/html directory and opening the index.html file.

By opening the documentation, which you do by going to the doc/html directory and opening the index.html file.

Adhere to code style#

PyConverter-XML2Py follows the PEP8 standard as outlined in the PyAnsys Developer’s Guide and implements style checking using pre-commit.

To ensure your code meets minimum code styling standards, run this code:

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

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

pre-commit install

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

$ git commit -am "added my cool feature"
black....................................................................Passed
blacken-docs.............................................................Passed
isort....................................................................Passed
flake8...................................................................Passed
codespell................................................................Passed
check for merge conflicts................................................Passed
debug statements (python)................................................Passed
Validate GitHub Workflows................................................Passed

Distributing#

If you would like to create either source or wheel files, start by installing the building requirements:

python -m pip install -e .[doc,tests]

Then, execute these commands:

python -m build
python -m twine check dist/*