diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst deleted file mode 100644 index c6c43286..00000000 --- a/.github/CONTRIBUTING.rst +++ /dev/null @@ -1,161 +0,0 @@ -Contributor Guide -================= - -This guide is intended to get new developers started with contributing to diffsims. - -Many potential contributors will be scientists with much expert knowledge but -potentially little experience with open-source code development. This guide is -primarily aimed at this audience, helping to reduce the barrier to contribution. - - -Start using diffsims --------------------- - -The best way to start understanding how diffsims is to use it. - -For developing the code the home of diffsims is on github and you'll see that -a lot of this guide boils down to using that platform well. so visit the -following link and poke around the code, issues, and pull requests: `diffsims -on Github `_. - -It's probably also worth visiting the `Github `_ home page -and going through the "boot camp" to get a feel for the terminology. - -In brief, to give you a hint on the terminology to search for, the contribution -pattern is: - -1. Setup git/github if you don't have it. -2. Fork diffsims on github. -3. Checkout your fork on your local machine. -4. Create a new branch locally where you will make your changes. -5. Push the local changes to your own github fork. -6. Create a pull request (PR) to the official diffsims repository. - -Note: You cannot mess up the main diffsims project. So when you're starting out be -confident to play, get it wrong, and if it all goes wrong you can always get a -fresh install of diffsims! - -PS: If you choose to develop in Windows/Mac you may find `Github Desktop -`_ useful. - - -Questions? ----------- - -Open source projects are all about community - we put in much effort to make -good tools available to all and most people are happy to help others start out. -Everyone had to start at some point and the philosophy of these projects -centers around the fact that we can do better by working together. - -Much of the conversation happens in 'public' using the 'issues' pages on -`Github `_ -- doing things in public can -be scary but it ensures that issues are identified and logged until dealt with. -This is also a good place to make a proposal for some new feature or tool that -you want to work on. - - -Good coding practice -==================== - -The most important aspects of good coding practice are: (1) to work in managable -branches, (2) develop good code style, (3) write tests for new functions, and (4) -document what the code does. Tips on these points are provided below. - - -Use git to work in managable branches -------------------------------------- - -Git is an open source "version control" system that enables you to can separate -out your modifications to the code into many versions (called branches) and -switch between them easily. Later you can choose which version you want to have -integrated into diffsims. - -You can learn all about Git `here `_! - -The most important thing to separate your contributions so that each branch is -small advancement on the "master" code or on another branch. - - -Get the style right -------------------- - -diffsims follows the Style Guide for Python Code - these are just some rules for -consistency that you can read all about in the `Python Style Guide -`_. - -To enforce this, we require that the following auto correction is applied at the -end of pull request. The simplest option is to run (from the home directory of -diffsims) - -Note that if you have recently run tests locally you may have a test generated -file diffsims/file_01.pickle on your machine, which should be deleted prior to -running the following code. - -Linux: - -.. code:: bash - - chmod +x pepstorm.sh - ./pepstorm.sh - git add . - git commit -m "autopep8 corrections" - -Windows: - -.. code:: batch - - pepstorm.bat - git add . - git commit -m "autopep8 corrections" - - -Writing tests -------------- - -diffsims aims to have all of the functions within it tested, which involves writing -short methods that call the functions and check output values agains known -answers. Good tests should depend on as few other features as possible so that -when they break we know exactly what caused it. - -diffsims uses the `pytest `_ library for testing. The -tests reside in the ``diffsims.tests`` module. To run them (from the diffsims project -folder): - -.. code:: bash - - pytest - - -Useful hints on testing: - -* When comparing integers, it's fine to use ``==``. When comparing floats use something like assert ``np.allclose(shifts,shifts_expected,atol=0.2)`` -* ``@pytest.mark.parametrize()`` is a very convenient decorator to test several - parameters of the same function without having to write to much repetitive - code, which is often error-prone. See `pytest documentation for more details - `_. -* We test the code coverage on pull requests, you can check the coverage on a - local branch using - -.. code:: bash - - pytest --cov=diffsims - -* Some useful fixtures (a basic diffraction pattern, a basic structure...) can - be found in conftest.py, you can just call these directly in the test suite. - - -Write documentation -------------------- - -Docstrings -- written at the start of a function and give essential information -about how it should be used, such as which arguments can be passed to it and -what the syntax should be. The docstrings need to follow the `numpy specification -`_, -as shown in `this example `_. - - - -Learn more -========== - -1. The Python programming language, `for beginners `__. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 0645ab60..b37ab67b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,32 +1,21 @@ ---- -name: Pull request -about: A pull request that fixes a bug or adds a feature +#### Description of the change ---- -**Release Notes** -> new feature / improvement / bugfix / developer change -Summary: 1 line per end-user relevant change +#### Progress of the PR -**What does this PR do? Please describe and/or link to an open issue.** -A clear and concise description of what the code in this PR does. Does it fix a bug or add a new feature? -If it is related to an open issue, reference it here. +- [ ] [Docstrings for all functions](https://github.com/numpy/numpy/blob/master/doc/example.py) +- [ ] Unit tests with pytest for all lines +- [ ] Clean code style by [running black](https://diffsims.readthedocs.io/en/latest/contributing.html#get-the-style-right) -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. - -**Are there any known issues? Do you need help?** -If the code isn't quite working as you want it to, tell us here so we can help you polish the code. - -**Work in progress?** -If you know there is more to do, make a checklist here: -- [ ] TODO 1 -- [ ] TODO 2 +#### Minimal example of the bug fix or new feature +```python +>>> from diffsims.utils import sim_utils +>>> # Your new feature... +``` #### For reviewers -- [ ] Check that the PR title is short, concise, and will make sense 1 year - later. -- [ ] Check that new functions are imported in corresponding `__init__.py`. -- [ ] Check that new features, API changes, and deprecations are mentioned in - the unreleased section in `CHANGELOG.md`. +- [ ] The PR title is short, concise, and will make sense 1 year later. +- [ ] New functions are imported in corresponding `__init__.py`. +- [ ] New features, API changes, and deprecations are mentioned in the + unreleased section in `CHANGELOG.rst`. diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index b1d41d4f..885e3383 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -3,10 +3,22 @@ name: build on: [push, pull_request] jobs: + # Make sure all necessary files will be included in a release + manifest: + name: check manifest + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-python@v2 + - name: Install dependencies + run: pip install manifix + - name: Check MANIFEST.in file + run: python setup.py manifix + build-with-pip: name: ${{ matrix.os }}/py${{ matrix.python-version }}/pip runs-on: ${{ matrix.os }} - timeout-minutes: 45 + timeout-minutes: 15 env: MPLBACKEND: agg strategy: diff --git a/CHANGELOG.md b/CHANGELOG.rst similarity index 54% rename from CHANGELOG.md rename to CHANGELOG.rst index f1595026..9346f844 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.rst @@ -1,45 +1,61 @@ -# Changelog +========= +Changelog +========= + All notable changes to this project will be documented in this file. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +The format is based on `Keep a Changelog `_, +and this project adheres to `Semantic Versioning +`_. -## Unreleased +Unreleased +========== -### Added -- extra parameters in diffraction pattern's plot method for drawing miller index labels next to the diffraction spots +Added +----- +- Extra parameters in diffraction pattern's plot method for drawing miller index labels + next to the diffraction spots - Option to use None for `scattering_params` which ignores atomic scattering -### Changed +Changed +------- - Minimal version of dependencies numpy >= 1.17 and tqdm >= 4.9 -## 2021-04-16 - version 0.4.2 +2021-04-16 - version 0.4.2 +========================== -### Added +Added +----- - Simulations now have a .get_as_mask() method (#154, #158) - Python 3.9 testing (#161) -### Fixed +Changed +------- +- Simulations now use a fractional (rather than absolute) min_intensity (#161) + +Fixed +----- - Precession simulations (#161) -### Changed -- Simulations now use a fractional (rather than absolute) min_intensity (#161) +2021-03-15 - version 0.4.1 +========================== -## 2021-03-15 - version 0.4.1 -### Changed -- `get_grid_beam_directions` default meshing changed to "spherified_cube_edge" from "spherified_cube_corner" +Changed +------- +- `get_grid_beam_directions` default meshing changed to "spherified_cube_edge" from + "spherified_cube_corner" -### Fixed -- `get_grid_beam_directions` now behaves correctly for the triclinic and monoclinic cases +Fixed +----- +- `get_grid_beam_directions` now behaves correctly for the triclinic and monoclinic + cases -## 2021-01-11 - version 0.4.0 -### Changed -- `get_grid_beam_directions`, now works based off of meshes -- the arguments in the `DiffractionGenerator` constructor and the `DiffractionLibraryGenerator.get_diffraction_library` function have been shuffled so that the former captures arguments related to "the instrument/physics" while the latter captures arguments relevant to "the sample/material". -- CI is now provided by github actions +2021-01-11 - version 0.4.0 +========================== -### Added -- API reference documentation via Read The Docs: https://diffsims.rtfd.io +Added +----- +- API reference documentation via Read The Docs: https://diffsims.readthedocs.io - New module: `sphere_mesh_generators` - New module: `detector_functions` - New module: `ring_pattern_utils` @@ -48,8 +64,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - more shape factor functions have been added - This project now keeps a Changelog -### Removed +Changed +------- +- `get_grid_beam_directions`, now works based off of meshes +- the arguments in the `DiffractionGenerator` constructor and the + `DiffractionLibraryGenerator.get_diffraction_library` function have been shuffled so + that the former captures arguments related to "the instrument/physics" while the + latter captures arguments relevant to "the sample/material". +- CI is now provided by github actions + +Removed +------- - Python 3.6 testing -### Fixed +Fixed +----- - ReciprocalLatticePoint handles having only one point/vector diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..153ae6e6 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,163 @@ +================= +Contributor Guide +================= + +This guide is intended to get new developers started with contributing to diffsims. + +Many potential contributors will be scientists with much expert knowledge but +potentially little experience with open-source code development. This guide is primarily +aimed at this audience, helping to reduce the barrier to contribution. + +We have a `Code of Conduct +`_ that must +be honoured by contributors. + +Start using diffsims +==================== + +The best way to start understanding how diffsims works is to use it. + +For developing the code the home of diffsims is on GitHub and you'll see that a lot of +this guide boils down to using that platform well. so visit the following link and poke +around the code, issues, and pull requests (PRs): `diffsims +on GitHub `_. + +It's probably also worth visiting the `GitHub guides `_ to +get a feel for the terminology. + +In brief, to give you a hint on the terminology to search for, the contribution pattern +is: + +1. Setup git/GitHub if you don't have it. +2. Fork diffsims on GitHub. +3. Checkout your fork on your local machine. +4. Create a new branch locally where you will make your changes. +5. Push the local changes to your own github fork. +6. Create a PR to the official diffsims repository. + +Note: You cannot mess up the main diffsims project. So when you're starting out be +confident to play, get it wrong, and if it all goes wrong you can always get a fresh +install of diffsims! + +PS: If you choose to develop in Windows/Mac you may find the `Github Desktop +`_ useful. + +Questions? +========== + +Open source projects are all about community - we put in much effort to make good tools +available to all and most people are happy to help others start out. Everyone had to +start at some point and the philosophy of these projects centers around the fact that we +can do better by working together. + +Much of the conversation happens in 'public' using the 'issues' pages on +`GitHub `_ -- doing things in public can be +scary but it ensures that issues are identified and logged until dealt with. This is +also a good place to make a proposal for some new feature or tool that you want to work +on. + +Good coding practice +==================== + +The most important aspects of good coding practice are: (1) to work in manageable +branches, (2) develop a good code style, (3) write tests for new functions, and (4) +document what the code does. Tips on these points are provided below. + +Use git to work in manageable branches +-------------------------------------- + +Git is an open source "version control" system that enables you to can separate out your +modifications to the code into many versions (called branches) and switch between them +easily. Later you can choose which version you want to have integrated into diffsims. + +You can learn all about Git `here `_! + +The most important thing is to separate your contributions so that each branch is a +small advancement on the "master" code or on another branch. + +Get the style right +------------------- + +diffsims closely follows the Style Guide for Python Code - these are just some rules for +consistency that you can read all about in the `Python Style Guide +`_. + +Please run the latest version of +`black `_ on +your newly added and modified files prior to each PR. + +Run and write tests +------------------- + +All functionality in diffsims is tested via the `pytest `_ +framework. The tests reside in the ``diffsims.tests`` module. Tests are short functions +that call functions in diffsims and compare resulting output values with known answers. +Good tests should depend on as few other features as possible so that when they break we +know exactly what caused it. + +Install necessary dependencies to run the tests:: + + pip install --editable .[tests] + +Some useful `fixtures `_ are available +in the ``conftest.py`` file. + +To run the tests:: + + pytest --cov --pyargs diffsims + +The ``--cov`` flag makes `coverage.py `_ +print a nice report in the terminal. For an even nicer presentation, you can use +``coverage.py`` directly:: + + coverage html + +Then, you can open the created ``htmlcov/index.html`` in the browser and inspect the +coverage in more detail. + +Useful hints on testing: + +- When comparing integers, it's fine to use ``==``. When comparing floats use something + like assert ``np.allclose(shifts, shifts_expected, atol=0.2)``. +- ``@pytest.mark.parametrize()`` is a convenient decorator to test several parameters of + the same function without having to write to much repetitive code, which is often + error-prone. See `pytest documentation for more details + `_. + +Build and write documentation +----------------------------- + +Docstrings -- written at the start of a function -- give essential information about how +it should be used, such as which arguments can be passed to it and what the syntax +should be. The docstrings follow the `NumPy specification +`_, +as shown in `this example `_. + +We use `Sphinx `_ for documenting functionality. +Install necessary dependencies to build the documentation:: + + pip install -e .[doc] + +Then, build the documentation from the ``doc`` directory:: + + 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/diffsims/doc/build/html/index.html`` in the address bar. + +Continuous integration (CI) +=========================== + +We use `GitHub Actions `_ to ensure that +diffsims can be installed on Windows, macOS and Linux. After a successful installation, +the CI server runs the tests. After the tests return no errors, code coverage is +reported to `Coveralls `_. + +Learn more +========== + +1. The Python programming language, `for beginners `__. diff --git a/MANIFEST.in b/MANIFEST.in index 1aba38f6..83337de7 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1 +1,10 @@ +include CHANGELOG.rst +include CONTRIBUTING.rst include LICENSE +include MANIFEST.in +include README.rst +include readthedocs.yaml +include setup.cfg +include setup.py + +recursive-include doc Makefile make.bat *.rst *.py diff --git a/README.rst b/README.rst index 8c98623b..22a52ae1 100644 --- a/README.rst +++ b/README.rst @@ -18,27 +18,12 @@ .. |doi| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3337900.svg .. _doi: https://doi.org/10.5281/zenodo.3337900 -diffsims is an open-source python library for simulating diffraction. +diffsims is an open-source Python library for simulating diffraction. If simulations performed using diffsims form a part of published work please -cite the DOI at the top of this page. +cite the DOI at the top of this page. You can find demos in the `diffsims-demos +`_ repository. See the `documentation +`_ for installation instructions, the API reference, +the changelog and more. diffsims is released under the GPL v3 license. - -Installation ------------- - -diffsims requires python 3 and conda - we suggest using the python 3 version of -`Miniconda `__ and creating a new environment -for diffsims using the following commands in the anaconda prompt:: - -$ conda create -n diffsims -$ conda activate diffsims - -The recommended way to install diffsims is then from conda-forge using:: - -$ conda install -c conda-forge diffsims - -Note that diffsims is also available via pip:: - -$ pip install diffsims diff --git a/diffsims/generators/diffraction_generator.py b/diffsims/generators/diffraction_generator.py index 0e0c1a0b..5e438e82 100644 --- a/diffsims/generators/diffraction_generator.py +++ b/diffsims/generators/diffraction_generator.py @@ -102,7 +102,7 @@ def integrand(theta): class DiffractionGenerator(object): - """Computes electron diffraction patterns for a crystal structure. + r"""Computes electron diffraction patterns for a crystal structure. 1. Calculate reciprocal lattice of structure. Find all reciprocal points within the limiting sphere given by :math:`\\frac{2}{\\lambda}`. @@ -123,26 +123,29 @@ class DiffractionGenerator(object): "lobato", "xtables" or None. If None is provided then atomic scattering is not taken into consideration. precession_angle : float - Angle about which the beam is precessed in degrees. Default is no precession. - shape_factor_model : function or string + Angle about which the beam is precessed in degrees. Default is + no precession. + shape_factor_model : func or str A function that takes excitation_error and `max_excitation_error` (and potentially kwargs) and returns an intensity scaling factor. If None defaults to - `shape_factor_models.linear`. A number of pre-programmed functions - are available via strings. - approximate_precession : boolean + `shape_factor_models.linear`. A number of pre-programmed + functions are available via strings. + approximate_precession : bool When using precession, whether to precisely calculate average excitation errors and intensities or use an approximation. minimum_intensity : float - Minimum intensity for a peak to be considered visible in the pattern (fractional from the maximum) - kwargs : + Minimum intensity for a peak to be considered visible in the + pattern (fractional from the maximum). + kwargs Keyword arguments passed to `shape_factor_model`. Notes ----- - * When using precession and approximate_precession=True, the shape factor - model defaults to Lorentzian; shape_factor_model is ignored. Only with - approximate_precession=False the custom shape_factor_model is used. + When using precession and approximate_precession=True, the shape + factor model defaults to Lorentzian; shape_factor_model is ignored. + Only with `approximate_precession=False` the + `custom shape_factor_model` is used. """ def __init__( diff --git a/diffsims/release_info.py b/diffsims/release_info.py index be3e310c..124392ab 100644 --- a/diffsims/release_info.py +++ b/diffsims/release_info.py @@ -1,11 +1,11 @@ name = "diffsims" -version = "0.4.3-dev" +version = "0.5.dev0" author = "Duncan Johnstone, Phillip Crout" -copyright = "Copyright 2017-2021, The pyXem Developers" +copyright = "Copyright 2017-2022, The pyXem developers" credits = [ "Duncan Johnstone", "Phillip Crout", - "Simon Hogas", + "Simon Høgås", "Ben Martineau", "Isabel Wood", "Håkon Wiik Ånes", diff --git a/diffsims/tests/conftest.py b/diffsims/tests/conftest.py index b3163ee4..2299d8b3 100644 --- a/diffsims/tests/conftest.py +++ b/diffsims/tests/conftest.py @@ -16,9 +16,9 @@ # You should have received a copy of the GNU General Public License # along with diffsims. If not, see . -import pytest from diffpy.structure import Atom, Lattice, Structure from orix.crystal_map import Phase +import pytest from diffsims.generators.diffraction_generator import DiffractionGenerator diff --git a/diffsims/tests/patterns/__init__.py b/diffsims/tests/patterns/__init__.py new file mode 100644 index 00000000..c5879ca8 --- /dev/null +++ b/diffsims/tests/patterns/__init__.py @@ -0,0 +1,17 @@ +# -*- coding: utf-8 -*- +# Copyright 2017-2022 The diffsims developers +# +# This file is part of diffsims. +# +# diffsims is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# diffsims is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with diffsims. If not, see . diff --git a/doc/changelog.rst b/doc/changelog.rst new file mode 100644 index 00000000..fde5735d --- /dev/null +++ b/doc/changelog.rst @@ -0,0 +1,3 @@ +.. This is a stub, see the top level CHANGELOG.rst file for the changelog. + +.. include:: ../CHANGELOG.rst \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py index 4278753d..b3d0547a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -51,7 +51,7 @@ intersphinx_mapping = { "diffpy.structure": ("https://www.diffpy.org/diffpy.structure", None), "matplotlib": ("https://matplotlib.org", None), - "numpy": ("https://docs.scipy.org/doc/numpy", None), + "numpy": ("https://numpy.org/doc/stable", None), "orix": ("https://orix.readthedocs.io/en/stable", None), "python": ("https://docs.python.org/3", None), "scipy": ("https://docs.scipy.org/doc/scipy/reference", None), @@ -71,16 +71,15 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "sphinx_rtd_theme" +html_theme = "furo" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] -# Logo -# html_logo = "_static/img/diffsims_logo.png" -# html_favicon = "_static/img/diffsims_logo.png" +# Syntax highlighting +pygments_style = "friendly" def linkcode_resolve(domain, info): diff --git a/doc/contributing.rst b/doc/contributing.rst new file mode 100644 index 00000000..1777ba46 --- /dev/null +++ b/doc/contributing.rst @@ -0,0 +1,3 @@ +.. This is a stub, see the top level CONTRIBUTING.rst file for the contributing guide. + +.. include:: ../CONTRIBUTING.rst \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index 1c099ae0..9b4907c6 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -2,89 +2,20 @@ diffsims ======== -.. toctree:: - :hidden: - - reference.rst - .. include:: ../README.rst -Contributing ------------- - -diffsims is a community maintained project. We welcome contributions in the form of bug -reports, feature requests, code, documentation, and more. `These guidelines -`_ describe how best to -contribute to. - -Related projects ----------------- - -Related, open-source projects that users of diffsims might find useful: - -- `pyxem `_: Python library for multi-dimensional - diffraction microscopy. -- `orix `_: Python library for handling crystal - orientation mapping data. -- `kikuchipy `_: Python library for processing and analysis of - electron backscatter diffraction (EBSD) patterns. - -Installation ------------- - -diffsims can be installed from `Anaconda `_, -the `Python Package Index `_ (``pip``), or from -source, and supports Python >= 3.6. - -We recommend you install it in a `conda environment -`_ -with the `Miniconda distribution`_:: - - $ conda create --name diffsims-env - $ conda activate diffsims-env - -If you prefer a graphical interface to manage packages and environments, install the -`Anaconda distribution`_ instead. - -.. _Miniconda distribution: https://docs.conda.io/en/latest/miniconda.html -.. _Anaconda distribution: https://docs.continuum.io/anaconda/ - -Anaconda -~~~~~~~~ - -Anaconda provides the easiest installation. In the Anaconda Prompt, terminal or Command -Prompt, install with:: - - $ conda install diffsims --channel conda-forge - -If you at a later time need to update the package:: - - $ conda update diffsims - -pip -~~~ - -To install with ``pip``, run the following in the Anaconda Prompt, terminal or Command -Prompt:: - - $ pip install diffsims - -If you at a later time need to update the package:: - - $ pip install --upgrade diffsims - -Install from source -~~~~~~~~~~~~~~~~~~~ - -To install diffsims from source, clone the repository from `GitHub -`_:: +.. toctree:: + :hidden: + :caption: Getting started - $ git clone https://github.com/pyxem/diffsims.git - $ cd diffsims - $ pip install --editable . + installation.rst + usage.rst -Changelog ---------- +.. toctree:: + :hidden: + :caption: Help & reference -Changes with each release can be viewed on the `GitHub release page -`_. + reference.rst + changelog.rst + contributing.rst + related_projects.rst diff --git a/doc/installation.rst b/doc/installation.rst new file mode 100644 index 00000000..67d14a65 --- /dev/null +++ b/doc/installation.rst @@ -0,0 +1,60 @@ +============ +Installation +============ + +diffsims can be installed from `Anaconda `_, the +`Python Package Index `_ (``pip``), or from source, +and supports Python >= 3.6. + +We recommend you install it in a `conda environment +`_ +with the `Miniconda distribution`_:: + + conda create --name diffsims-env python=3.9 + conda activate diffsims-env + +If you prefer a graphical interface to manage packages and environments, install the +`Anaconda distribution`_ instead. + +.. _Miniconda distribution: https://docs.conda.io/en/latest/miniconda.html +.. _Anaconda distribution: https://docs.continuum.io/anaconda/ + +.. _install-with-anaconda: + +Anaconda +-------- + +Anaconda provides the easiest installation. In the Anaconda Prompt, terminal or Command +Prompt, install with:: + + conda install diffsims --channel conda-forge + +If you at a later time need to update the package:: + + conda update diffsims + +.. _install-with-pip: + +Pip +--- + +To install with ``pip``, run the following in the Anaconda Prompt, terminal or Command +Prompt:: + + pip install diffsims + +If you at a later time need to update the package:: + + pip install --upgrade diffsims + +.. _install-from-source: + +Install from source +------------------- + +To install diffsims from source, clone the repository from `GitHub +`_:: + + git clone https://github.com/pyxem/diffsims.git + cd diffsims + pip install -e . diff --git a/doc/reference.rst b/doc/reference.rst index 2fd67e3d..8eacb27e 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -7,8 +7,8 @@ generated from their docstrings. Some of the docstrings contain examples. .. caution:: - diffsims is in an alpha stage, and there will likely be breaking changes with each - release. + diffsims is in continuous development (alpha stage), so expect some breaking changes + with each release. .... diff --git a/doc/related_projects.rst b/doc/related_projects.rst new file mode 100644 index 00000000..819a4537 --- /dev/null +++ b/doc/related_projects.rst @@ -0,0 +1,12 @@ +================ +Related projects +================ + +Related, open-source projects that users of diffsims might find useful: + +- `pyxem `_: Python library for multi-dimensional + diffraction microscopy. Uses diffsims. +- `orix `_: Python library for handling crystal + orientation mapping data. +- `kikuchipy `_: Python library for processing and analysis of + electron backscatter diffraction (EBSD) patterns. Uses diffsims. diff --git a/doc/usage.rst b/doc/usage.rst new file mode 100644 index 00000000..980c27f9 --- /dev/null +++ b/doc/usage.rst @@ -0,0 +1,5 @@ +===== +Usage +===== + +See the `demos `_ for how to use diffsims. diff --git a/readthedocs.yml b/readthedocs.yaml similarity index 69% rename from readthedocs.yml rename to readthedocs.yaml index 749f0da4..da7390fe 100644 --- a/readthedocs.yml +++ b/readthedocs.yaml @@ -1,4 +1,4 @@ -# .readthedocs.yml +# .readthedocs.yaml # Read the Docs configuration file # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details @@ -9,14 +9,21 @@ version: 2 sphinx: configuration: doc/conf.py +# Set the version of Python and other tools you might need +build: + os: ubuntu-20.04 + tools: + python: "3.9" + # Build doc in all formats (HTML, PDF and ePub) -formats: all +formats: + - htmlzip + - pdf # Python environment for building the docs python: - version: 3.8 install: - method: pip path: . extra_requirements: - - doc + - doc \ No newline at end of file diff --git a/setup.cfg b/setup.cfg index 8d96bbb8..88b03425 100644 --- a/setup.cfg +++ b/setup.cfg @@ -6,12 +6,20 @@ xfail_strict = True [coverage:run] source = diffsims -include = */diffsims/* omit = - */diffsims/release_info.py - */diffsims/__init__.py - + setup.py + diffsims/release_info.py relative_files = True [coverage:report] precision = 2 + +[manifix] +known_excludes = + .* + .*/** + .git/** + **/*.pyc + doc/_build/** + htmlcov/** + *.code-workspace \ No newline at end of file diff --git a/setup.py b/setup.py index ad66fded..f5f9f41d 100644 --- a/setup.py +++ b/setup.py @@ -25,7 +25,7 @@ # tests. From setuptools: # https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies extra_feature_requirements = { - "doc": ["sphinx >= 3.0.2", "sphinx-rtd-theme >= 0.4.3"], + "doc": ["furo", "sphinx >= 3.0.2"], "tests": ["pytest >= 5.4", "pytest-cov >= 2.8.1", "coverage >= 5.0"], } extra_feature_requirements["dev"] = ["black >= 19.3b0", "pre-commit >= 1.16"] + list( @@ -58,19 +58,19 @@ packages=find_packages(), extras_require=extra_feature_requirements, install_requires=[ - "diffpy.structure >= 3.0.0", # First Python 3 support - "matplotlib >= 3.1.1", + "diffpy.structure >= 3.0.0", # First Python 3 support + "matplotlib >= 3.1.1", "numba", - "numpy >= 1.17", - "orix >= 0.5.0", + "numpy >= 1.17", + "orix >= 0.5.0", "psutil", - "scipy >= 0.15", - "tqdm >= 4.9", + "scipy >= 0.15", + "tqdm >= 4.9", "transforms3d", ], python_requires=">=3.6", package_data={ - "": ["LICENSE", "README.rst", "readthedocs.yml"], + "": ["LICENSE", "README.rst", "readthedocs.yaml"], "diffsims": ["*.py"], }, )