orix is a community maintained project. We welcome contributions in the form of bug reports, feature requests, code, documentation, and more. These guidelines provide resources on how best to contribute.
For new users, checking out the GitHub guides are recommended.
Questions, comments, and feedback¶
Set up a development installation¶
Make a local copy of your forked repository and change directories:
$ git clone https://github.com/your-username/orix.git $ cd orix
upstream remote to the main orix repository:
$ git remote add upstream https://github.com/pyxem/orix.git
$ conda create --name orix $ conda activate orix
Then, install the required dependencies while making the development version available
globally (in the
$ pip install --editable .[dev]
This installs all necessary development dependencies, including those for running tests and building documentation.
The code making up orix is formatted closely following the Style Guide for Python Code with The Black Code style. We use
pre-commit to run
black automatically prior to each
local commit. Please install it in your environment:
$ pre-commit install
Next time you commit some code, your code will be formatted inplace according to the default black configuration.
Comment lines should preferably be limited to 72 characters.
Package imports should be structured into three blocks with blank lines between them
(descending order): standard library (like
typing), third party packages
matplotlib) and finally orix imports.
Create a new feature branch:
$ git checkout master -b your-awesome-feature-name
When you’ve made some changes you can view them with:
$ git status
Add and commit your created, modified or deleted files:
$ git add my-file-or-directory $ git commit -s -m "An explanatory commit message"
Keep your branch up-to-date¶
Switch to the
$ git checkout master
Fetch changes and update
$ git pull upstream master --tags
Update your feature branch:
$ git checkout your-awesome-feature-name $ git merge master
Build and write documentation¶
We use Sphinx for documenting functionality. Install necessary dependencies to build the documentation:
$ pip install --editable .[doc]
Then, build the documentation from the
$ cd doc $ make html
The documentation’s HTML pages are built in the
doc/build/html directory from files
in the reStructuredText (reST)
plaintext markup language. They should be accessible in the browser by typing
file:///your-absolute/path/to/orix/doc/build/html/index.html in the address bar.
Tips for writing Jupyter Notebooks that are meant to be converted to reST text files by nbsphinx:
All notebooks should have a Markdown (MD) cell with this message at the top, “This notebook is part of the orix documentation https://orix.rtfd.io. Links to the documentation won’t work from the notebook.”, and have
"nbsphinx": "hidden"in the cell metadata so that the message is not visible when displayed in the documentation.
_ = ax.imshow(...)to disable Matplotlib output if a Matplotlib command is the last line in a cell.
Refer to our API reference with this general MD
[Vector3d.zvector()](reference.rst#orix.vector.Vector3d.zvector). Remember to add the parentheses
Reference external APIs via standard MD like
The Sphinx gallery thumbnail used for a notebook is set by adding the
nbsphinx-thumbnailtag to a code cell with an image output. The notebook must be added to the gallery in the README.rst to be included in the documentation pages.
Run and write tests¶
All functionality in orix is tested via the pytest
framework. The tests reside in a
test directory within each module. Tests are short
methods that call functions in orix and compare resulting output values with known
answers. Install necessary dependencies to run the tests:
$ pip install --editable .[tests]
Some useful fixtures are available
To run the tests:
$ pytest --cov --pyargs orix
--cov flag makes coverage.py
print a nice report in the terminal. For an even nicer presentation, you can use
$ coverage html
Then, you can open the created
htmlcov/index.html in the browser and inspect the
coverage in more detail.