diff --git a/.appveyor.yml b/.appveyor.yml index 065790bc201..2efeee89a72 100644 --- a/.appveyor.yml +++ b/.appveyor.yml @@ -7,9 +7,9 @@ environment: matrix: - PYTHON_VERSION: "2.7" - PYTHON_VERSION: "3.6" + - PYTHON_VERSION: "3.7" platform: - - x86 - x64 install: @@ -26,9 +26,9 @@ install: - cmd: sed -i -e s/python=3/python=%PYTHON_VERSION%/ environment.yml - cmd: conda env create -q -f environment.yml - cmd: activate devel + - cmd: pip install sphinx_rtd_theme==0.2.5b1.post1 -f https://unidata-python.s3.amazonaws.com/wheelhouse/index.html - cmd: python --version - cmd: conda list - - cmd: if %PYTHON_VERSION% == 2.7 conda install -q enum34 - cmd: pip install ".[test]" - cmd: flake8 --version @@ -36,11 +36,11 @@ install: build: off test_script: - - cmd: set TEST_DATA_DIR=%APPVEYOR_BUILD_FOLDER%\\testdata - - cmd: python setup.py test --addopts "-s --junitxml=tests.xml --flake8 --mpl --cov=metpy" -# - cmd: cd docs -# - cmd: make html -# - cmd: cd .. + - cmd: set TEST_DATA_DIR=%APPVEYOR_BUILD_FOLDER%\\staticdata + - cmd: python setup.py test --addopts "-s --junitxml=tests.xml --flake8 --mpl --cov=metpy -W error::metpy.deprecation.MetpyDeprecationWarning" + - cmd: cd docs + - cmd: make overridecheck html + - cmd: cd .. on_finish: - ps: $wc = New-Object 'System.Net.WebClient' diff --git a/.circleci/config.yml b/.circleci/config.yml new file mode 100644 index 00000000000..7b86a8d9415 --- /dev/null +++ b/.circleci/config.yml @@ -0,0 +1,46 @@ +# Python CircleCI 2.0 configuration file +# +# Check https://circleci.com/docs/2.0/language-python/ for more details +# +version: 2 +jobs: + build: + docker: + - image: circleci/python:3-stretch + + working_directory: ~/repo + + steps: + - checkout + + # Download and cache dependencies + - restore_cache: + keys: + - v1-dependencies-{{ checksum "setup.py" }} + # fallback to using the latest cache if no exact match is found + - v1-dependencies- + + - run: + name: install dependencies + command: | + sudo apt-get install libgeos-dev libproj-dev + python3 -m venv venv + . venv/bin/activate + pip install --upgrade pytest + pip install ".[test]" "shapely<1.5.17.post1" --upgrade --upgrade-strategy=eager -f https://unidata-python.s3.amazonaws.com/wheelhouse/index.html + + - save_cache: + paths: + - ./venv + key: v1-dependencies-{{ checksum "setup.py" }} + + # run tests! + - run: + name: run tests + command: | + . venv/bin/activate + python setup.py test --addopts "-s --flake8 --mpl" + + - store_artifacts: + path: test-reports + destination: test-reports diff --git a/.codeclimate.yml b/.codeclimate.yml index e9d8baa7337..9c5c77ddd57 100644 --- a/.codeclimate.yml +++ b/.codeclimate.yml @@ -1,22 +1,39 @@ -engines: -# duplication: -# enabled: true -# config: -# languages: -# - python +version: "2" +checks: + file-lines: + enabled: false + similar-code: + enabled: false + method-lines: + enabled: false + argument-count: + config: + threshold: 10 + method-complexity: + config: + threshold: 15 + +plugins: + sonar-python: + enabled: true + config: + test_patterns: + - "metpy/**/tests/*.py" + checks: + python:S3776: + enabled: false + python:S107: + enabled: false + python:S1542: + enabled: false + pep8: enabled: true checks: E501: enabled: false - radon: - enabled: true - -ratings: - paths: - - "**/*.py" -exclude_paths: +exclude_patterns: - "versioneer.py" - "metpy/_version.py" - "metpy/io/_nexrad_msgs/msg*.py" diff --git a/.codecov.yml b/.codecov.yml index f252536cbe1..f3e2fb2ef3d 100644 --- a/.codecov.yml +++ b/.codecov.yml @@ -22,7 +22,9 @@ coverage: tests: target: 100% - paths: "metpy/.*/tests/.*" + paths: + - "metpy/.*/tests/.*" + - "metpy/tests/.*" notify: gitter: diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 41a19eff1da..bc6966d1115 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,7 +1,7 @@ # These owners will be the default owners for everything in the repo. # Unless a later match takes precedence, global owners # will be requested for review when someone opens a pull request. -* @dopplershift @jrleeman +* @dopplershift @zbruick # Order is important; the last matching pattern takes the most precedence. # When someone opens a pull request that only modifies specified file types, only diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 00000000000..ece1f802be7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,19 @@ +### For feature requests + +Include a clear description and an example or even a scholarly source of information about how the calculation, plot, etc. works + +### For bugs + +Try to include: +- Code Sample, a copy-pastable example if possible +- A ["Minimal, Complete and Verifiable Example"](http://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports) will make it much easier for maintainers to help you + +```python +# Your code here + +``` +- Problem description: this should explain **why** the current behavior is a problem and why the expected output is a better solution. +- Expected output +- Versions. Include the output of: + * `python --version` + * `python -c 'import metpy; print(metpy.__version__)' diff --git a/.gitignore b/.gitignore index 74f30b93d6c..3523e8bf0d4 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ .coverage .coverage.* .cache +.pytest_cache .ipynb_checkpoints/ diff --git a/.lgtm.yml b/.lgtm.yml new file mode 100644 index 00000000000..8b9a8a49246 --- /dev/null +++ b/.lgtm.yml @@ -0,0 +1,8 @@ +path_classifiers: + generated: + - metpy/_version.py + library: + - versioneer.py + - metpy/deprecation.py + test: + - exclude: metpy/testing.py diff --git a/.mailmap b/.mailmap index b9e643e8773..377a102715d 100644 --- a/.mailmap +++ b/.mailmap @@ -1,10 +1,22 @@ John Leeman +Kevin Goebbert + Tyler Wixtrom Tyler Wixtrom Brian Mapes Kristen Pozsonyi - - +Daryl Herzmann +Kishan Mehta +Matt Wilson +Andrew Huang + + +Tim Supinie +Zach Bruick +Joy Monteiro +Steven Decker + +Claude Dicaire <31997745+eliteuser26@users.noreply.github.com> \ No newline at end of file diff --git a/.stickler.yml b/.stickler.yml index 85d905bcffe..00dbbcd1271 100644 --- a/.stickler.yml +++ b/.stickler.yml @@ -3,4 +3,5 @@ linters: ignore: 'F405' max-line-length: 95 files: - ignore: ['metpy/_version.py'] + ignore: + - 'metpy/_version.py' diff --git a/.travis.yml b/.travis.yml index e0b7eaa4dbf..f099e24f830 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,7 +1,8 @@ # After changing this file, check it on: # http://lint.travis-ci.org/ language: python -sudo: false +sudo: required +dist: xenial addons: artifacts: @@ -16,7 +17,11 @@ addons: - gfortran - libproj-dev +git: + depth: 150 + python: + - 3.7 - 3.6 - 2.7 @@ -30,7 +35,10 @@ env: - secure: "MOw+6pAQ8s7XX1U9Pbgw8SIuz5MHODj6PXe6xCSIyGR14/0KFNiR9s6NEIa9i7qnp7HOq/V2M9ZFPPioQCrL8k5V4XzZfNz6kXGUT8DoSAAnAAnDWy4yMRxYMlEcjSY8l0KZ9B3szxypkLh0Qd9+pHZYvRSLt8A8UcZSVSNGDjg=" - WHEELHOUSE="https://unidata-python.s3.amazonaws.com/wheelhouse/index.html" - WHEELDIR="wheelhouse/" - - EXTRA_INSTALLS="test,cdm" + # Shapely dependency needed to keep from using Shapely's manylinux wheels + # which use a different geos that what we build cartopy with on Travis + - EXTRA_PACKAGES="shapely<1.5.17.post1" + - EXTRA_INSTALLS="test" - MPLLOCALFREETYPE="1" - TEST_OUTPUT_CONTROL="-s" - GH_PAGES_DIR="$HOME/gh-pages" @@ -42,34 +50,25 @@ matrix: include: - python: 2.7 env: - - VERSIONS="numpy==1.10.0 matplotlib==1.4.0 scipy==0.14.0 pint==0.8" + - VERSIONS="numpy==1.12.0 matplotlib==2.0.0 scipy==0.17.0 pint==0.8 xarray==0.10.7" - TASK="coverage" - TEST_OUTPUT_CONTROL="" - - python: 3.4 - env: - - python: 3.5 - env: - - python: "3.6-dev" + - python: "3.7-dev" env: PRE="--pre" + - python: "3.7-dev" + env: TASK="docs" PRE="--pre" - python: nightly env: PRE="--pre" allow_failures: - - python: "3.6-dev" + - python: "3.7-dev" - python: nightly before_install: - # Shapely dependency needed to keep from using Shapely's manylinux wheels - # which use a different geos that what we build cartopy with on Travis - # We hardcode the sphinx_rtd_theme to lock in our build with patch for + # We hard-code the sphinx_rtd_theme to lock in our build with patch for # version chooser - pip install --upgrade pip; - pip install --upgrade setuptools; - - if [[ $TASK == "docs" ]]; then - if ! git describe --tags; then git fetch --depth=150; fi; - export EXTRA_INSTALLS="cdm,doc,examples"; - export EXTRA_PACKAGES="Cython pillow shapely<1.5.17.post1 sphinx_rtd_theme==0.2.5b1.post1 pytest recommonmark"; - ls $HOME/local/lib/; - if [[ ! -f $HOME/local/lib/libproj.so ]]; then + - if [[ ! -f $HOME/local/lib/libproj.so ]]; then wget http://download.osgeo.org/proj/proj-4.9.3.tar.gz; tar xf proj-4.9.3.tar.gz; pushd proj-4.9.3; @@ -78,12 +77,15 @@ before_install: sed -i "" -e s/-I// proj.pc; make install; popd; - fi; - export PKG_CONFIG_PATH="$HOME/local/lib/pkgconfig"; - export LD_LIBRARY_PATH="$HOME/local/lib"; - pkg-config --modversion proj; + fi; + - export PKG_CONFIG_PATH="$HOME/local/lib/pkgconfig"; + - export LD_LIBRARY_PATH="$HOME/local/lib"; + - pkg-config --modversion proj; + - if [[ $TASK == "docs" ]]; then + export EXTRA_INSTALLS="doc,examples"; + export EXTRA_PACKAGES="$EXTRA_PACKAGES pillow sphinx_rtd_theme==0.2.5b1.post1 pytest"; else - export TEST_OPTS="--flake8 --mpl"; + export TEST_OPTS="--flake8 --mpl -W error::metpy.deprecation.MetpyDeprecationWarning"; if [[ $TRAVIS_PYTHON_VERSION == 3.6 ]]; then export EXTRA_PACKAGES="$EXTRA_PACKAGES flake8-bugbear"; fi; @@ -93,31 +95,33 @@ before_install: fi; fi; - mkdir $WHEELDIR; + # Cython needs to be installed before even downloading CartoPy + - pip install Cython; - pip download -d $WHEELDIR ".[$EXTRA_INSTALLS]" $EXTRA_PACKAGES -f $WHEELHOUSE $PRE $VERSIONS; - touch $WHEELDIR/download_marker && ls -lrt $WHEELDIR; - travis_wait pip wheel -w $WHEELDIR $EXTRA_PACKAGES -f $WHEELHOUSE $PRE $VERSIONS; - - pip install $EXTRA_PACKAGES --upgrade --no-index -f file://$PWD/$WHEELDIR $VERSIONS; - - travis_wait pip wheel -w $WHEELDIR ".[$EXTRA_INSTALLS]" $EXTRA_PACKAGES -f $WHEELHOUSE $PRE $VERSIONS; + - pip install $EXTRA_PACKAGES --upgrade --upgrade-strategy=eager --no-index -f file://$PWD/$WHEELDIR $VERSIONS; + - travis_wait 30 pip wheel -w $WHEELDIR ".[$EXTRA_INSTALLS]" $EXTRA_PACKAGES -f $WHEELHOUSE $PRE $VERSIONS; - rm -f $WHEELDIR/MetPy*.whl; install: - - pip install ".[$EXTRA_INSTALLS]" --upgrade --no-index $PRE -f file://$PWD/$WHEELDIR $VERSIONS; + - pip install ".[$EXTRA_INSTALLS]" --upgrade --upgrade-strategy=eager --no-index $PRE -f file://$PWD/$WHEELDIR $VERSIONS; script: - if [[ $TASK == "docs" ]]; then - export TEST_DATA_DIR=${TRAVIS_BUILD_DIR}/testdata; + export TEST_DATA_DIR=${TRAVIS_BUILD_DIR}/staticdata; pushd docs; - make clean html linkcheck; + make clean overridecheck html linkcheck O=-W; export DOC_BUILD_RESULT=$?; popd; - if [[ $TRAVIS_PYTHON_VERSION == 3.6 ]]; then + if [[ $TRAVIS_PYTHON_VERSION == 3.6* ]]; then MPLBACKEND='agg' pytest --doctest-modules -k "not test" metpy; export DOC_TEST_RESULT=$?; else export DOC_TEST_RESULT=0; fi; - doc8 --file-encoding utf8 README.rst docs/; - if [[ $DOC_BUILD_RESULT -ne 0 || $DOC_TEST_RESULT -ne 0 || $? -ne 0 ]]; then + doc8 README.rst docs/; + if [[ $? -ne 0 || $DOC_BUILD_RESULT -ne 0 || $DOC_TEST_RESULT -ne 0 ]]; then false; fi; else diff --git a/AUTHORS.txt b/AUTHORS.txt index dd001a839b6..cd556b06da3 100644 --- a/AUTHORS.txt +++ b/AUTHORS.txt @@ -1,15 +1,42 @@ +The following are the contributors of code within MetPy: +UCAR/Unidata Aaron Hill +Abby Kenyon Alex Haberlie +Andrew Huang +Assela Pathirana +Brian Mapes +Bryan Guarente +Claude Dicaire +Dan Dawson +Daryl Herzmann +Denis Sergeev Eric Bruning John Leeman +Jon Thielen Jonathan Helmus +Joy Monteiro Kevin Goebbert -kpozsonyi +Kishan Mehta +Kristen Pozsonyi +Leonardo Uieda +Lucas Sterzinger +Matt Wilson Michael James -mmorello1 Nathan Wendt Patrick Marsh +Raul Mendez Ryan May Sean Arms Shawn Murdzek +Stefan Hofer +Steven Decker +Tim Supinie +Tyler Wixtrom +Varden Nadkarni +Warren Pettee Will Holmgren +Zach Bruick +eliteuser26 +kstilwell +mmorello1 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000000..5e93b124e73 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,46 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at support-python@unidata.ucar.edu. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 120000 index 49d1b98f97e..00000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1 +0,0 @@ -docs/CONTRIBUTING.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..8c3b9a2630b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,283 @@ +# Contributors Guide + +Interested in helping build MetPy? Have code from your research that you believe others will +find useful? Have a few minutes to tackle an issue? In this guide we will get you setup and +integrated into contributing to MetPy! + +## Introduction +First off, thank you for considering contributing to MetPy. MetPy is community-driven +project. It's people like you that make MetPy useful and successful. There are many ways +to contribute, from writing tutorials or examples, improvements to the documentation, +submitting bug reports and feature requests, or even writing code which can be incorporated +into MetPy for everyone to use. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue, assessing changes, and +helping you finalize your pull requests. + +So, please take a few minutes to read through this guide and get setup for success with your +MetPy contributions. We're glad you're here! + +## What Can I Do? +* Tackle any [issues](https://github.com/Unidata/MetPy/issues) you wish! We have a special + label for issues that beginners might want to try. Have a look at our + [current beginner issues.](https://github.com/unidata/metpy/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty%3A+Beginner%22) + Also have a look at if the issue is already assigned to someone - this helps us make sure + that work is not duplicated if the issue is already being worked on by Unidata Staff. + +* Contribute code you already have. It does not need to be perfect! We will help you clean + things up, test it, etc. + +* Make a tutorial or example of how to do something. + +* Improve documentation of a feature you found troublesome. + +* File a new issue if you run into problems! + +## Ground Rules +The goal is to maintain a diverse community that's pleasant for everyone. Please +be considerate and respectful of others by following our +[code of conduct](https://github.com/Unidata/MetPy/blob/master/CODE_OF_CONDUCT.md). + +Other items: + +* Each pull request should consist of a logical collection of changes. You can + include multiple bug fixes in a single pull request, but they should be related. + For unrelated changes, please submit multiple pull requests. +* Do not commit changes to files that are irrelevant to your feature or bugfix + (eg: .gitignore). +* Be willing to accept criticism and work on improving your code; we don't want + to break other users' code, so care must be taken not to introduce bugs. +* Be aware that the pull request review process is not immediate, and is + generally proportional to the size of the pull request. + +## Reporting a bug +The easiest way to get involved is to report issues you encounter when using MetPy or by +requesting something you think is missing. + +* Head over to the [issues](https://github.com/Unidata/MetPy/issues) page. +* Search to see if your issue already exists or has even been solved previously. +* If you indeed have a new issue or request, click the "New Issue" button. +* Fill in as much of the issue template as is relevant. Please be as specific as possible. + Include the version of the code you were using, as well as what operating system you + are running. If possible, include complete, minimal example code that reproduces the problem. + +## Setting up your development environment +We recommend using the [conda](https://conda.io/docs/) package manager for your Python +environments. Our recommended setup for contributing is: + +* Install [miniconda](https://docs.conda.io/en/latest/miniconda.html) on your system. +* Install git on your system if it is not already there (install XCode command line tools on + a Mac or git bash on Windows) +* Login to your GitHub account and make a fork of the + [MetPy repository](https://github.com/unidata/metpy/) by clicking the "Fork" button. +* Clone your fork of the MetPy repository (in terminal on Mac/Linux or git shell/ + GUI on Windows) in the location you'd like to keep it. We are partial to creating a + ``git_repos`` directory in our home folder. + ``git clone https://github.com/your-user-name/metpy.git`` +* Navigate to that folder in the terminal or in Anaconda Prompt if you're on Windows. + ``cd metpy`` +* Connect your repository to the upstream (main project). + ``git remote add unidata https://github.com/unidata/metpy.git`` +* Create the development environment by running ``conda env create``. This will install + all of the packages in the ``environment.yml`` file. +* Activate our new development environment ``source activate devel`` on Mac/Linux or + ``activate devel`` on Windows. +* Make an editable install of MetPy by running ``pip install -e .`` + +Now you're all set! You have an environment called ``devel`` that you can work in. You'll need +to make sure to activate that environment next time you want to use it after closing the +terminal or your system. If you want to get back to the root environment, just run +``source deactivate`` (just ``deactivate`` on Windows). + +## Pull Requests + +The changes to the MetPy source (and documentation) should be made via GitHub pull requests +against ``master``, even for those with administration rights. While it's tempting to +make changes directly to ``master`` and push them up, it is better to make a pull request so +that others can give feedback. If nothing else, this gives a chance for the automated tests to +run on the PR. This can eliminate "brown paper bag" moments with buggy commits on the master +branch. + +During the Pull Request process, before the final merge, it's a good idea to rebase the branch +and squash together smaller commits. It's not necessary to flatten the entire branch, but it +can be nice to eliminate small fixes and get the merge down to logically arranged commits. This +can also be used to hide sins from history--this is the only chance, since once it hits +``master``, it's there forever! + +**Working on your first Pull Request?** You can learn how from this *free* video series +[How to Contribute to an Open Source Project on GitHub](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github), Aaron Meurer's [tutorial on the git workflow](https://www.asmeurer.com/git-workflow/), or the guide [“How to Contribute to Open Source"](https://opensource.guide/how-to-contribute/). + +Commit the changes you made. Chris Beams has written a [guide](https://chris.beams.io/posts/git-commit/) on how to write good commit messages. + +Push to your fork and [submit a pull request]( https://github.com/Unidata/metpy/compare/). +For the Pull Request to be accepted, you need to agree to the +MetPy Contributor License Agreement (CLA). This will be handled automatically +upon submission of a Pull Request. +See [here](https://github.com/Unidata/MetPy/blob/master/CLA.md) for more +explanation and rationale behind MetPy's CLA. + +## Documentation +Now that you've made your awesome contribution, it's time to tell the world how to use it. +Writing documentation strings is really important to make sure others use your functionality +properly. Didn't write new functions? That's fine, but be sure that the documentation for +the code you touched is still in great shape. It is not uncommon to find some strange wording +or clarification that you can take care of while you are here. If you added a new function +make sure that it gets marked as included if appropriate in the GEMPAK conversion table. + +You can write examples in the documentation if they are simple concepts to demonstrate. If +your feature is more complex, consider adding to the examples or tutorials for MetPy. + +You can build the documentation locally to see how your changes will look. +* Navigate to the docs folder ``cd docs`` +* Remove any old builds and build the current docs ``make clean html`` +* Open ``docs/build/html/index.html`` and see your changes! + +## Tests +Unit tests are the lifeblood of the project, as it ensures that we can continue to add and +change the code and stay confident that things have not broken. Running the tests requires +``pytest``, which is easily available through ``conda`` or ``pip``. It was also installed if +you made our default ``devel`` environment. + +### Running Tests +Running the tests can be done by running ``py.test`` + +Running the whole test suite isn't that slow, but can be a burden if you're working on just +one module or a specific test. It is easy to run tests on a single directory: + + py.test metpy/calc + +A specific test can be run as: + + py.test -k test_my_test_func_name + +### Writing Tests +Tests should ideally hit all of the lines of code added or changed. We have automated +services that can help track down lines of code that are missed by tests. Watching the +coverage has even helped find sections of dead code that could be removed! + +Let's say we are adding a simple function to add two numbers and return the result as a float +or as a string. (This would be a silly function, but go with us here for demonstration +purposes.) + + def add_as_float_or_string(a, b, as_string=False): + res = a + b + if as_string: + return string(res) + return res + +I can see two easy tests here: one for the results as a float and one for the results as a +string. If I had added this to the ``calc`` module, I'd add those two tests in +``tests/test_calc.py``. + + def test_add_as_float_or_string_defaults(): + res = add_as_float_or_string(3, 4) + assert(res, 7) + + + def test_add_as_float_or_string_string_return(): + res = add_as_float_or_string(3, 4, as_string=True) + assert(res, '7') + +There are plenty of more advanced testing concepts, like dealing with floating point +comparisons, parameterizing tests, testing that exceptions are raised, and more. Have a look +at the existing tests to get an idea of some of the common patterns. + +### Image tests +Some tests (for matplotlib plotting code) are done as an image comparison, using the +pytest-mpl plugin. To run these tests, use: + + py.test --mpl + +When adding new image comparison tests, start by creating the baseline images for the tests: + + py.test --mpl-generate-path=baseline + +That command runs the tests and saves the images in the ``baseline`` directory. +For MetPy this is generally ``metpy/plots/tests/baseline/``. We recommend using the ``-k`` flag +to run only the test you just created for this step. + +For more information, see the [docs for pytest-mpl](https://github.com/astrofrog/pytest-mpl). + + +## Cached Data Files +MetPy keeps some test data, as well as things like shape files for US counties in a data cache +supported by the pooch library. To add files to this, please ensure they are as small as +possible. Put the files in the `staticdata` directory. Then run this command in the metpy +directory (that contains the `static-data-manifest.txt` file)to recreate the data registry: + +`python -c "import pooch; pooch.make_registry('staticdata', 'metpy/static-data-manifest.txt')"` + +Make sure that no system files (like `.DS_Store`) are in the manifest and add it to your +contribution. + +## Code Style +MetPy uses the Python code style outlined in [PEP8](https://pep8.org). For better or worse, this +is what the majority of the Python world uses. The one deviation is that line length limit is +95 characters. 80 is a good target, but some times longer lines are needed. + +While the authors are no fans of blind adherence to style and so-called project "clean-ups" +that go through and correct code style, MetPy has adopted this style from the outset. +Therefore, it makes sense to enforce this style as code is added to keep everything clean and +uniform. To this end, part of the automated testing for MetPy checks style. To check style +locally within the source directory you can use the ``flake8`` tool. Running it +from the root of the source directory is as easy as running ``pytest --flake8`` in the base +of the repository. + +You can also just submit your PR and the kind robots will comment on all style violations as +well. It can be a pain to make sure you have the right number of spaces around things, imports +in order, and all of the other nits that the bots will find. It is very important though as +this consistent style helps us keep MetPy readable, maintainable, and uniform. + +## What happens after the pull request +You've make your changes, documented them, added some tests, and submitted a pull request. +What now? + +### Automated Testing +First, our army of never sleeping robots will begin a series of automated checks. +The test suite, documentation, style, and more will be checked on various versions of Python +with current and legacy packages. Travis CI will run testing on Linux and Mac, Appveyor will +run tests on Windows. Other services will kick in and check if there is a drop in code coverage +or any style variations that should be corrected. If you see a red mark by a service, something +failed and clicking the "Details" link will give you more information. We're happy to help if +you are stuck. + +The robots can be difficult to satisfy, but they are there to help everyone write better code. +In some cases, there will be exceptions to their suggestions, but these are rare. If you make +changes to your code and push again, the tests will automatically run again. + +### Code Review +At this point you're waiting on us. You should expect to hear at least a comment within a +couple of days. We may suggest some changes or improvements or alternatives. + +Some things that will increase the chance that your pull request is accepted quickly: + +* Write tests. +* Follow [PEP8][https://pep8.org] for style. (The `flake8` utility can help with this.) +* Write a [good commit message][https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html]. + +Pull requests will automatically have tests run by Travis. This includes +running both the unit tests as well as the `flake8` code linter. + +### Merging +Once we're all happy with the pull request, it's time for it to get merged in. Only the +maintainers can merge pull requests and you should never merge a pull request you have commits +on as it circumvents the code review. If this is your first or second pull request, we'll +likely help by rebasing and cleaning up the commit history for you. As your developement skills +increase, we'll help you learn how to do this. + + +## More Questions? +If you're stuck somewhere or are interested in being a part of the community in +other ways, feel free to contact us: +* [MetPy's Gitter Channel](https://gitter.im/Unidata/MetPy) +* ["metpy" tag on Stack Overflow](https://stackoverflow.com/questions/tagged/metpy) +* [Unidata's Python support address](mailto:support-python@unidata.ucar.edu) +* [python-users](https://www.unidata.ucar.edu/support/#mailinglists) mailing list + +## Futher Reading +There are a ton of great resources out there on contributing to open source and on the +importance of writing tested and maintainable software. +* [GitHub's Contributing to Open Source Guide](https://guides.github.com/activities/contributing-to-open-source/) +* [Zen of Scientific Software Maintenance](https://jrleeman.github.io/ScientificSoftwareMaintenance/) diff --git a/LICENSE b/LICENSE index a431ab1d692..869aca32cd1 100644 --- a/LICENSE +++ b/LICENSE @@ -1,30 +1,29 @@ -Copyright (c) 2008-2016, MetPy Developers. +BSD 3-Clause License + +Copyright (c) 2008-2019, MetPy Developers All rights reserved. Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: +modification, are permitted provided that the following conditions are met: - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. - * Neither the name of the MetPy Developers nor the names of any - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. +* Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/MANIFEST.in b/MANIFEST.in index 9b2403a7aa9..e7b68b08ab8 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -5,6 +5,7 @@ include LICENSE include CONTRIBUTING.md include versioneer.py include metpy/_version.py +include metpy/static-data-manifest.txt recursive-include examples *.py *.txt recursive-include tutorials *.py *.txt recursive-include docs * diff --git a/README.rst b/README.rst index 31de27619e2..71804ca2959 100644 --- a/README.rst +++ b/README.rst @@ -71,12 +71,17 @@ MetPy MetPy is a collection of tools in Python for reading, visualizing and performing calculations with weather data. -MetPy is still in an early stage of development, and as such -**no APIs are considered stable.** While we won't break things -just for fun, many things may still change as we work through -design issues. +MetPy follows `semantic versioning `_ in its version number. With our +current 0.x version, that implies that MetPy's APIs (application programming interfaces) are +still evolving (we won't break things just for fun, but many things are still changing as we +work through design issues). Also, for a version `0.x.y`, we change `x` when we +release new features, and `y` when we make a release with only bug fixes. -We support Python 2.7 as well as Python >= 3.4. +We support Python >= 3.6 and currently support Python 2.7. + +NOTE: We are dropping support for Python 2.7 in Fall 2019. See +`here `_ for more +information. Need Help? ---------- @@ -90,7 +95,9 @@ Important Links - Source code repository: https://github.com/Unidata/MetPy - HTML Documentation : http://unidata.github.io/MetPy +- Unidata Python Gallery: https://unidata.github.io/python-gallery/ - Issue tracker: http://github.com/Unidata/MetPy/issues +- "metpy" tagged questions on Stack Overflow: https://stackoverflow.com/questions/tagged/metpy - Gitter chat room: https://gitter.im/Unidata/MetPy - Say Thanks: https://saythanks.io/to/unidata @@ -103,11 +110,21 @@ Other required packages: - Matplotlib - Pint -Python versions older than 3.4 require the enum34 package, which is a backport +Python 2.7 requires the enum34 package, which is a backport of the standard library enum module. There is also an optional dependency on the pyproj library for geographic -projections (used with CDM interface). +projections (used with cross sections, grid spacing calculation, and the GiniFile interface). + +See the `installation guide `_ +for more information. + +Code of Conduct +--------------- +We want everyone to feel welcome to contribute to MetPy and participate in discussions. In that +spirit please have a look at our `code of conduct`__. + +__ https://github.com/Unidata/MetPy/blob/master/CODE_OF_CONDUCT.md Contributing ------------ diff --git a/SUPPORT.md b/SUPPORT.md index 9e9ac49ab29..5a92cf48f2c 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -5,9 +5,17 @@ are many ways to contact us: ## Help using MetPy Need some help using MetPy to solve your problem? -* [Gitter Chatroom](https://gitter.im/Unidata/MetPy) -* [Unidata Python User’s Mailing List](https://www.unidata.ucar.edu/support/#mailinglists) +* [Stack Overflow](https://stackoverflow.com/questions/tagged/metpy): Ask a question using the + "metpy" tag. This is the highly preferred option as it allows the community to benefit from + answers to the questions, forming a readily-searched knowledge base. It's also likely to + result in the quickest response, as not only are the MetPy developers watching, but + community members can also chime in if they know the answer. +* [Unidata Python Support email](mailto:support-python@unidata.ucar.edu): Send an email to + Unidata's Python support email address. +* [Gitter](https://gitter.im/Unidata/MetPy): text-based chat with the developers; sign in + using GitHub or Twitter. * [MetPy on Twitter](https://twitter.com/MetPy) +* [Unidata Python User’s Mailing List](https://www.unidata.ucar.edu/support/#mailinglists) ## Issues Find a problem with MetPy? Looking for a feature we don't have? File an issue! diff --git a/conftest.py b/conftest.py index d140f83a2e2..dd2ae12e831 100644 --- a/conftest.py +++ b/conftest.py @@ -4,6 +4,7 @@ """Configure pytest for metpy.""" import matplotlib +import matplotlib.pyplot import numpy import pint import pytest diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md deleted file mode 100644 index 7873b8a43c3..00000000000 --- a/docs/CONTRIBUTING.md +++ /dev/null @@ -1,122 +0,0 @@ -# Contributing - -## Introduction -First off, thank you for considering contributing to MetPy. MetPy is community-driven -project, so it's people like you that make MetPy useful and successful. - -Following these guidelines helps to communicate that you respect the time of the -developers managing and developing this open source project. In return, they -should reciprocate that respect in addressing your issue, assessing changes, and -helping you finalize your pull requests. - -We love contributions from community members, just like you! There are many ways -to contribute, from writing tutorial or example Jupyter notebooks, improvements -to the documentation, submitting bug report and feature requests, or even writing -code which can be incorporated into MetPy for everyone to use. If you get stuck at -any point you can create an [issue on GitHub](https://github.com/Unidata/MetPy/issues) -or contact us at one of the other channels mentioned below. - -For more information on contributing to open source projects, -[GitHub's own guide](https://guides.github.com/activities/contributing-to-open-source/) -is a great starting point. Also, checkout the [Zen of Scientific Software Maintenance](https://jrleeman.github.io/ScientificSoftwareMaintenance/) -for some guiding principles on how to create high quality scientific software contributions. - -## Getting Started - -Interested in helping build MetPy? Have code from your research that you believe others will -find useful? Have a few minutes to tackle an issue? In this guide we will get you setup and -integrated into contributing to MetPy! - -## What Can I Do? -* Tackle any [issues](https://github.com/Unidata/MetPy/issues) you wish! We have a special - label for issues that beginners might want to try. Have a look at our - [current beginner issues.](https://github.com/unidata/metpy/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty%3A+Beginner%22) - -* Contribute code you already have. It doesn’t need to be perfect! We will help you clean - things up, test it, etc. - -* Make a tutorial or example of how to do something. - -## How Can I Talk to You? -Discussion of MetPy development often happens in the issue tracker and in pull requests. -In addition, the developers monitor the -[gitter chat room](https://gitter.im/Unidata/MetPy?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) -for the project as well. - -## Ground Rules -The goal is to maintain a diverse community that's pleasant for everyone. Please -be considerate and respectful of others. Other items: - -* Each pull request should consist of a logical collection of changes. You can - include multiple bug fixes in a single pull request, but they should be related. - For unrelated changes, please submit multiple pull requests. -* Do not commit changes to files that are irrelevant to your feature or bugfix - (eg: .gitignore). -* Be willing to accept criticism and work on improving your code; we don't want - to break other users' code, so care must be taken not to introduce bugs. -* Be aware that the pull request review process is not immediate, and is - generally proportional to the size of the pull request. - -## Reporting a bug -When creating a new issue, please be as specific as possible. Include the version -of the code you were using, as well as what operating system you are running. -If possible, include complete, minimal example code that reproduces the problem. - -## Pull Requests -**Working on your first Pull Request?** You can learn how from this *free* video series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github), Aaron Meurer's [tutorial on the git workflow](http://www.asmeurer.com/git-workflow/), or the guide [“How to Contribute to Open Source"](https://opensource.guide/how-to-contribute/). -We love pull requests from everyone. Fork, then clone the repo: - - git clone git@github.com:your-username/metpy.git - -Install metpy: - - pip install . - -Install py.test (at least version 2.4) and make sure the tests pass: - - pip install pytest - py.test - -Make your change. Add tests for your change. Make the tests pass: - - py.test - -Commit the changes you made. Chris Beams has written a [guide](https://chris.beams.io/posts/git-commit/) on how to write good commit messages. - -Push to your fork and [submit a pull request][pr]. - -[pr]: https://github.com/Unidata/metpy/compare/ - -For the Pull Request to be accepted, you need to agree to the -MetPy Contributor License Agreement (CLA). This will be handled automatically -upon submission of a Pull Request. -See [here](https://github.com/Unidata/MetPy/blob/master/CLA.md) for more -explanation and rationale behind MetPy's CLA. - -As part of the Pull Request, be sure to add yourself to the -[list of contributors](https://github.com/Unidata/MetPy/blob/master/AUTHORS.txt). -We want to make sure we acknowledge the hard work you've generously contributed -here. - -## Code Review -Once you've submitted a Pull Request, at this point you're waiting on us. You -should expect to hear at least a comment within a couple of days. -We may suggest some changes or improvements or alternatives. - -Some things that will increase the chance that your pull request is accepted: - -* Write tests. -* Follow [PEP8][pep8] for style. (The `flake8` utility can help with this.) -* Write a [good commit message][commit]. - -Pull requests will automatically have tests run by Travis. This includes -running both the unit tests as well as the `flake8` code linter. - -[pep8]: http://pep8.org -[commit]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html - -## Other Channels -If you're interested in contacting us or being a part of the community in -other ways, feel free to contact us in -[MetPy's Gitter Channel](https://gitter.im/Unidata/MetPy) or through Unidata's -[python-users](https://www.unidata.ucar.edu/support/#mailinglists) mailing list. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 120000 index 00000000000..44fcc634393 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1 @@ +../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index 49d919e5de8..78a03fd052e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,184 +1,33 @@ -# Makefile for Sphinx documentation +# Minimal makefile for Sphinx documentation # # You can set these variables from the command line. -SPHINXOPTS = -W +SPHINXOPTS = SPHINXBUILD = sphinx-build SPHINXAUTOGEN = sphinx-autogen -PAPER = -BUILDDIR = build -HTMLBUILDDIR = $(BUILDDIR)/html +SPHINXPROJ = MetPy SOURCEDIR = . -GITREMOTE = $(shell git config --get remote.docs.url) - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext +BUILDDIR = build +# Put it first so that "make" without argument is like "make help". help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +# Sphinx doesn't know to clean out the debris from sphinx-gallery clean: rm -rf $(BUILDDIR)/* $(SOURCEDIR)/examples $(SOURCEDIR)/tutorials $(SOURCEDIR)/api/generated -autogen: - $(SPHINXAUTOGEN) -i -t $(SOURCEDIR)/_templates -o $(SOURCEDIR)/api/generated $(SOURCEDIR)/api/*.rst - -html: autogen - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(HTMLBUILDDIR) - @echo - @echo "Build finished. The HTML pages are in $(HTMLBUILDDIR)." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MetPy.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MetPy.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/MetPy" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MetPy" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." +# Check that all functions in modules with template overrides are present in the doc file +overridecheck: + python override_check.py -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." +.PHONY: help Makefile -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +# Manual autogen needed so we can specify the -i option so that imported names +# are included in generation +%: Makefile + echo Running sphinx-autogen + @$(SPHINXAUTOGEN) -i -t $(SOURCEDIR)/_templates -o $(SOURCEDIR)/api/generated $(SOURCEDIR)/api/*.rst + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/NWS_10-201.pdf b/docs/_static/NWS_10-201.pdf new file mode 100644 index 00000000000..fce9966846a Binary files /dev/null and b/docs/_static/NWS_10-201.pdf differ diff --git a/docs/_static/Smithsonian1951.pdf b/docs/_static/Smithsonian1951.pdf new file mode 100644 index 00000000000..bb962778d4c Binary files /dev/null and b/docs/_static/Smithsonian1951.pdf differ diff --git a/docs/_static/pop_ver.js b/docs/_static/pop_ver.js index 8fdd0a98e98..8013f12aacb 100644 --- a/docs/_static/pop_ver.js +++ b/docs/_static/pop_ver.js @@ -6,11 +6,11 @@ $(document).ready(function() { var mylist = $("#version-list"); mylist.empty(); mylist.append($("