diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 41e6c69f0..a4a45e764 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -37,7 +37,7 @@ jobs: channel-priority: strict python-version: ${{ matrix.python-version }} channels: conda-forge - environment-file: build_envs/environment.yml + environment-file: ci/environment.yml - name: Install uxarray run: | @@ -49,7 +49,7 @@ jobs: - name: Run Coverage Tests run: | - python -m pytest test -v --cov=./src/uxarray --cov-report=xml + python -m pytest test -v --cov=./uxarray --cov-report=xml - name: Upload code coverage to Codecov uses: codecov/codecov-action@v2.1.0 diff --git a/.github/workflows/upstream-dev-ci.yml b/.github/workflows/upstream-dev-ci.yml index 4f45f05c8..da92a6365 100644 --- a/.github/workflows/upstream-dev-ci.yml +++ b/.github/workflows/upstream-dev-ci.yml @@ -31,7 +31,7 @@ jobs: mamba-version: '*' python-version: 3.8 channels: conda-forge - environment-file: build_envs/upstream-dev-environment.yml + environment-file: ci/upstream-dev-environment.yml - name: Install uxarray run: | @@ -39,4 +39,4 @@ jobs: - name: Running Tests run: | - python -m pytest test -v --cov=./src/uxarray --cov-report=xml + python -m pytest test -v --cov=./uxarray --cov-report=xml diff --git a/.readthedocs.yml b/.readthedocs.yml index 56aecbf9e..f95974b18 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -16,4 +16,4 @@ sphinx: configuration: docs/conf.py conda: - environment: build_envs/environment.yml + environment: ci/environment.yml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..791b44efd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,9 @@ +# Contributing to Uxarray + +Anyone can contribute to and participate in the Uxarray project +at any levels of project development! We conduct all of our work +in the open, and all of our work is Open Source Licensed. + +Please see our +[Contributor’s Guide](https://uxarray.readthedocs.io/en/latest/contributing.html) +for detailed information! diff --git a/INSTALLATION.md b/INSTALLATION.md new file mode 100644 index 000000000..2302d3793 --- /dev/null +++ b/INSTALLATION.md @@ -0,0 +1,5 @@ +# How to install Uxarray + +Please see our +[Uxarray Installation](https://uxarray.readthedocs.io/en/latest/installation.html) + instructions for detailed information! diff --git a/README.md b/README.md index 222e5a743..c36ad084f 100644 --- a/README.md +++ b/README.md @@ -21,18 +21,17 @@ for contribution guidelines can be found when clicking `New Issue` under the `Is [Uxarray Documentation](https://uxarray.readthedocs.io/en/latest) -[Project Raijin Homepage](https://raijin.ucar.edu/) +[Uxarray Contributor’s Guide](https://uxarray.readthedocs.io/en/latest/contributing.html) -[SEATS Project Homepage]() +[Uxarray Installation](https://uxarray.readthedocs.io/en/latest/installation.html) -[Project Raijin Contributor's Guide](https://raijin.ucar.edu/contributing.html) +[Project Raijin Homepage](https://raijin.ucar.edu/) -[SEATs Project Contributor's Guide]() +[Project Raijin Contributor's Guide](https://raijin.ucar.edu/contributing.html) -# Installation and build instructions +[SEATS Project Homepage]() -Please see our documentation for -[installation and build instructions](https://github.com/UXARRAY/uxarray/blob/main/INSTALLATION.md). +[SEATs Project Contributor's Guide]() # Citing Uxarray diff --git a/build_envs/environment.yml b/ci/environment.yml similarity index 100% rename from build_envs/environment.yml rename to ci/environment.yml diff --git a/build_envs/upstream-dev-environment.yml b/ci/upstream-dev-environment.yml similarity index 100% rename from build_envs/upstream-dev-environment.yml rename to ci/upstream-dev-environment.yml diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 000000000..2f56c78fc --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,8 @@ +Contributor's Guide +=================== + +Anyone can contribute to and participate in the Uxarray project +at any levels of project development! We conduct all of our work +in the open, and all of our work is Open Source Licensed. + +Please see our Contributor’s Guide soon here! diff --git a/docs/index.rst b/docs/index.rst index 294281953..c0414b0ad 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,6 +29,7 @@ following ugrid conventions. More information on ugrid conventions can be found :maxdepth: 2 ./installation + ./contributing ./api ./examples ./citation diff --git a/docs/installation.rst b/docs/installation.rst index b39d51cfa..d62bc19c0 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -2,95 +2,85 @@ Installation ============ This installation guide includes only the Uxarray installation and build instructions. -Please refer to `Uxarray Contributor's Guide `_ for installation of -the project. + +Please refer to `Uxarray Contributor's Guide `_ for +detailed information about how to contribute to the uxarray project. Installing Uxarray via Conda --------------------------------- +---------------------------- -The easiest way to install Uxarray is using +The easiest way to install Uxarray along with its dependencies is via `Conda `_:: - conda create -n uxarray -c conda-forge uxarray - -where "uxarray" is the name of a new conda environment, which can then be -activated using:: - - conda activate uxarray - -If you somewhat need to make use of other software packages, such as Matplotlib, -Cartopy, Jupyter, etc. with Uxarray, you may wish to install into your :code:`uxarray` -environment. The following :code:`conda create` command can be used to create a new -:code:`conda` environment that includes some of these additional commonly used Python -packages pre-installed:: - - conda create -n uxarray -c conda-forge uxarray matplotlib cartopy jupyter - -Alternatively, if you already created a conda environment using the first -command (without the extra packages), you can activate and install the packages -in an existing environment with the following commands:: - - conda activate uxarray # or whatever your environment is called - conda install -c conda-forge matplotlib cartopy jupyter - + conda install -c conda-forge uxarray - -Also, note that the Conda package manager automatically installs all `required` +Note that the Conda package manager automatically installs all `required` dependencies of Uxarray, meaning it is not necessary to explicitly install -Xarraywhen creating an environment and installing Uxarray. +Xarray or other required packages when installing Uxarray. If you are interested in learning more about how Conda environments work, please visit the `managing environments `_ page of the Conda documentation. +Installing Uxarray via PyPI +--------------------------- + +An alternative to Conda is using pip:: -Building Uxarray from source --------------------------------- + pip install uxarray -Building Uxarray from source code is a fairly straightforward task, but +Installing Uxarray from source (Github) +--------------------------------------- + +Installing Uxarray from source code is a fairly straightforward task, but doing so should not be necessary for most users. If you `are` interested in -building Uxarray from source, you will need the following packages to be -installed. +installing Uxarray from source (e.g. maybe for obtaining the latest +development version), you will need to get the latest version of the code:: + + git clone https://github.com/UXARRAY/uxarray.git + cd uxarray -Required dependencies for building and testing Uxarray -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Required dependencies for installing and testing Uxarray from source +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following packages should be installed (in your active conda +environment):: - Python 3.7+ - `pytest `_ (For tests only) - `xarray `_ +The next section describes how to setup conda environment with these +dependencies. +How to create a Conda environment for installing Uxarray +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -How to create a Conda environment for building Uxarray -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The Uxarray source code includes a conda environment definition file in -the :code:`/build_envs` folder under the root directory that can be used to create a -development environment containing all of the packages required to build Uxarray. -The file :code:`environment.yml` is intended to be used on Linux systems and macOS. -The following commands should work on Windows, Linux, and macOS:: +The Uxarray source code includes a conda environment definition file +(:code:`environment.yml`) in the :code:`/ci` folder under the root +directory that can be used to create a development environment +containing all of the packages required to build Uxarray. The +following commands should work on Windows, Linux, and macOS:: - conda env create -f build_envs/environment.yml + conda env create -f ci/environment.yml conda activate uxarray_build +Installing Uxarray from source +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Installing Uxarray -^^^^^^^^^^^^^^^^^^^^^^ - -Once the dependencies listed above are installed, you can install Uxarray -with running the following command from the root-directory:: +Once the dependencies listed above are installed, you can install +Uxarray with running the following command from the root-directory:: pip install . For compatibility purposes, we strongly recommend using Conda to configure your build environment as described above. - -Testing a Uxarray build +Testing a Uxarray code base ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A Uxarray build can be tested from the root directory of the source code -repository using the following command (Explicit installation of the +A Uxarray code base can be tested from the root directory of the source +code repository using the following command (Explicit installation of the `pytest `_ package may be required, please see above):: diff --git a/setup.py b/setup.py index ec16804c3..8546a92f8 100644 --- a/setup.py +++ b/setup.py @@ -26,8 +26,7 @@ def version(): python_requires='>=3.7', install_requires=requirements, description= - """Uxarray looks to implement xarray capabilities with ugrid conventions to - facilitate data visualization with unstructured grids""", + """Unstructured grid model reading and recognizing with xarray.""", long_description=long_description, long_description_content_type='text/markdown', classifiers=[ @@ -41,12 +40,8 @@ def version(): 'Topic :: Scientific/Engineering', ], include_package_data=True, - package_dir={ - '': 'src', - 'uxarray': 'src/uxarray', - }, + packages=find_packages(exclude=["docs", "test", "docs.*", "test.*"]), # namespace_packages=['UXARRAY'], - packages=['uxarray'], url='https://github.com/UXARRAY/uxarray', project_urls={ # 'Documentation': 'https://uxarray.readthedocs.io', diff --git a/test/test_placeholder.py b/test/test_placeholder.py index 7d9abc93b..59b0acc4b 100644 --- a/test/test_placeholder.py +++ b/test/test_placeholder.py @@ -6,7 +6,7 @@ # Import from directory structure if coverage test, or from installed # packages otherwise if "--cov" in str(sys.argv): - import src.uxarray + import uxarray else: import uxarray diff --git a/src/uxarray/__init__.py b/uxarray/__init__.py similarity index 100% rename from src/uxarray/__init__.py rename to uxarray/__init__.py