diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..26e7a42 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,58 @@ +# +# Build documentation and deploy +# +name: Docs + +on: + # pull_request: + push: + branches: + - main + paths: + - 'docs/**' + - '.github/workflows/**' + +jobs: + build: + runs-on: ubuntu-20.04 + defaults: + run: + shell: bash -l {0} + + steps: + # Checks-out your repository under $GITHUB_WORKSPACE + - name: Checkout + uses: actions/checkout@v2.4.0 + + # Install Mambaforge with conda-forge dependencies + - name: Setup Mambaforge + uses: conda-incubator/setup-miniconda@v2.1.1 + with: + activate-environment: gmt-examples + environment-file: environment.yml + python-version: 3.8 + channels: conda-forge,nodefaults + channel-priority: strict + miniforge-version: latest + miniforge-variant: Mambaforge + mamba-version: "*" + use-mamba: true + + # Show installed pkg information for postmortem diagnostic + - name: List installed packages + run: mamba list + + - name: Build the website + run: make -C docs clean html + + - name: Deploy to gh-pages + if: success() && github.event_name == 'push' + # Don't use tags: https://julienrenaux.fr/2019/12/20/github-actions-security-risk/ + uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build/html/ + # Only keep the latest commit to avoid bloating the repository + force_orphan: true + user_name: 'github-actions[bot]' + user_email: 'github-actions[bot]@users.noreply.github.com' diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d807264 --- /dev/null +++ b/.gitignore @@ -0,0 +1,15 @@ +# Sphinx documentation +docs/_build/ + +# Visual Studio Code +.vscode/ + +# Environments +.env + +# Backup copies / swap files +*~ +.*.swp + +# macOS +.DS_Store diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..47d5438 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,133 @@ +# Contributor Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders 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, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +``pwessel at hawaii dot edu``, ``leouieda at gmail dot com``, or +``meghanj at hawaii dot edu``. All complaints will be reviewed and investigated +promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available +at [https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2bc033c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,35 @@ +# Contributing Guidelines + +:tada: **First off, thank you for considering contributing to our project!** :tada: + +This is a community-driven project, so it's people like you that make it useful and +successful. +These are some of the many ways to contribute: + +* :bug: Submitting bug reports and feature requests +* :memo: Writing tutorials or examples +* :mag: Fixing typos and improving the documentation +* :people_holding_hands: Community engagement and outreach + +If you get stuck at any point you can create an +[issue](https://github.com/GenericMappingTools/gmt-examples/issues) on GitHub or +get in touch through the [GMT Forum](https://forum.generic-mapping-tools.org/). + +For more information on contributing to open source projects, +[GitHub's own guide](https://opensource.guide/how-to-contribute) +is a great starting point if you are new to version control. + +Detailed instructions for contributors to the GMT Examples project can be found +in the [contributors guide](https://www.generic-mapping-tools.org/gmt-examples/contributing.html). + +## Ground Rules + +The goal is to maintain a diverse community that's pleasant for everyone. +**Please be considerate and respectful of others**. +Everyone must abide by our [Code of Conduct](CODE_OF_CONDUCT.md) and we encourage all to +read it carefully. + +## The `AUTHORS.md` file + +Anyone who has contributed a pull request to the project is welcome to add +themselves to the `AUTHORS.md` file. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..52bd145 --- /dev/null +++ b/LICENSE @@ -0,0 +1,395 @@ +Attribution 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More_considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution 4.0 International Public License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution 4.0 International Public License ("Public License"). To the +extent this Public License may be interpreted as a contract, You are +granted the Licensed Rights in consideration of Your acceptance of +these terms and conditions, and the Licensor grants You such rights in +consideration of benefits the Licensor receives from making the +Licensed Material available under these terms and conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + d. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + e. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + f. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + g. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + h. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + i. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + j. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + k. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + 4. If You Share Adapted Material You produce, the Adapter's + License You apply must not prevent recipients of the Adapted + Material from complying with this Public License. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material; and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. \ No newline at end of file diff --git a/README.md b/README.md index 0ab01a7..f94ae0a 100644 --- a/README.md +++ b/README.md @@ -1 +1,22 @@ # GMT Examples + +This repository contains tutorials and gallery examples for the Generic Mapping +Tools. + +## Contributing + +:tada: Thank you for considering contributing to our project! :tada: Please +refer to the [contributors guide](https://www.generic-mapping-tools.org/gmt-examples/contributing.html) +for more guidance. + +## Acknowledgements + +The gmt-examples structure is based on [PyGMT](https://github.com/GenericMappingTools/pygmt) +with style from [GMT](https://github.com/GenericMappingTools/gmt). Many examples +are translated from the [PyGMT user guide](https://pygmt.org). + +## License + +[![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png)](http://creativecommons.org/licenses/by/4.0/) +This work is licensed under a +[Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/). diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/favicon.png b/docs/_static/favicon.png new file mode 100644 index 0000000..d0de14d Binary files /dev/null and b/docs/_static/favicon.png differ diff --git a/docs/_static/fonts/Atkinson-Hyperlegible-Bold-102a.woff2 b/docs/_static/fonts/Atkinson-Hyperlegible-Bold-102a.woff2 new file mode 100644 index 0000000..19a58ea Binary files /dev/null and b/docs/_static/fonts/Atkinson-Hyperlegible-Bold-102a.woff2 differ diff --git a/docs/_static/fonts/Atkinson-Hyperlegible-BoldItalic-102a.woff2 b/docs/_static/fonts/Atkinson-Hyperlegible-BoldItalic-102a.woff2 new file mode 100644 index 0000000..43f253e Binary files /dev/null and b/docs/_static/fonts/Atkinson-Hyperlegible-BoldItalic-102a.woff2 differ diff --git a/docs/_static/fonts/Atkinson-Hyperlegible-Italic-102a.woff2 b/docs/_static/fonts/Atkinson-Hyperlegible-Italic-102a.woff2 new file mode 100644 index 0000000..d35d3a7 Binary files /dev/null and b/docs/_static/fonts/Atkinson-Hyperlegible-Italic-102a.woff2 differ diff --git a/docs/_static/fonts/Atkinson-Hyperlegible-Regular-102a.woff2 b/docs/_static/fonts/Atkinson-Hyperlegible-Regular-102a.woff2 new file mode 100644 index 0000000..99b3c6f Binary files /dev/null and b/docs/_static/fonts/Atkinson-Hyperlegible-Regular-102a.woff2 differ diff --git a/docs/_static/fonts/LICENSE b/docs/_static/fonts/LICENSE new file mode 100644 index 0000000..f3d445a --- /dev/null +++ b/docs/_static/fonts/LICENSE @@ -0,0 +1,46 @@ +ATKINSON HYPERLEGIBLE FONT LICENSE +Copyright © 2020, Braille Institute of America, Inc., https://www.brailleinstitute.org/freefont with Reserved Typeface +Name Atkinson Hyperlegible Font. +GENERAL +Copyright Holder allows the Font to be used, studied, modified and redistributed freely as long as it is not sold by +itself. The Font, including any derivative works, may be bundled, embedded, redistributed and/or sold with any software +or other work provided that the Reserved Typeface Name is not used on, in or by any derivative work. The Font and +derivatives, however, cannot be released under any other type of license. The requirement for the Font to remain under +this license does not apply to any document created using the Font or any of its derivatives. +DEFINITIONS +"Author" refers to any designer, engineer, programmer, technical writer or other person who contributed to the Font +Software. +“Copyright Holder” refers to Braille Institute of America, Inc. +“Font” refers to the Atkinson Hyperlegible Font developed by Copyright Holder. +"Font Software" refers to the set of files released by Copyright Holder under this license. This may include source +files, build scripts and documentation. +"Modified Version" refers to any derivative made by adding to, deleting, or substituting -- in part or in whole -- any +of the components of the Original Version, by changing formats or by porting the Font Software to a new environment. +"Original Version" refers to the collection of the Font Software components as distributed by Copyright Holder. +"Reserved Typeface Name" refers to the name Atkinson Hayperlegible Font. +PERMISSION & CONDITIONS +Permission is hereby granted, free of charge, to any person obtaining a copy of the Font Software, to use, study, copy, +merge, embed, modify, redistribute, and sell modified and unmodified copies of the Font Software, subject to the +following conditions: +1) Neither the Font Software nor any of its individual components, in Original Version or Modified Version, may be sold +by itself. +2) The Original Version or Modified Version of the Font Software may be bundled, redistributed and/or sold with any +other software, provided that each copy contains the above copyright notice and this license. These can be included +either as stand-alone text files, human-readable headers or in the appropriate machine-readable metadata fields within +text or binary files as long as those fields can be easily viewed by the user. +3) No Modified Version of the Font Software may use the Reserved Typeface Name unless explicit written permission is +granted by Copyright Holder. This restriction only applies to the primary font name as presented to the users. +4) The name of Copyright Holder or the Author(s) of the Font Software shall not be used to promote, endorse or advertise +any Modified Version or any related software or other product, except: +(a) to acknowledge the contribution(s) of Copyright Holder and the Author(s); or +(b) with the prior written permission of Copyright Holder. +5) The Font Software, modified or unmodified, in part or in whole, must be distributed entirely under this license, and +must not be distributed under any other license. +TERMINATION +This license shall immediately terminate and become null and void if any of the above conditions are not met. +DISCLAIMER +THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO +ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT, TRADEMARK +OR OTHER RIGHT. IN NO EVENT SHALL COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY +GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF THE USE OF OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE. diff --git a/docs/_static/style.css b/docs/_static/style.css new file mode 100644 index 0000000..c4a640b --- /dev/null +++ b/docs/_static/style.css @@ -0,0 +1,72 @@ +/* Set max width of the content */ +.wy-nav-content { + max-width: 1000px; +} + +/* See https://github.com/GenericMappingTools/gmt/pull/1605 */ +.rst-content dl dt { + font-weight: normal; +} + +body { + font-family: "Atkinson Hyperlegible", sans-serif; + font-size: 1.05em; +} + +h1, h2, h3, h4, h5, h6 { + font-family: "Atkinson Hyperlegible", sans-serif; + font-weight: "normal" +} + +/* style for example gallery */ +.gmtgallery li { + list-style: none!important; + width: 180px!important; + display: inline-grid!important; + margin-right: 15px!important; +} + +/* style for gmt movies */ +.gmtmovie li { + list-style: none; + width: 45%; + display: inline-grid; + margin: 10px; +} + +/* Set tab-width to 2 spaces */ +.highlight { + tab-size: 2; +} + +/* Atkinson Hyperlegible regular */ +@font-face { + font-family: "Atkinson Hyperlegible"; + src: url("./fonts/Atkinson-Hyperlegible-Regular-102a.woff2") format('woff2'); + font-weight: normal; + font-style: normal; +} + +/* Atkinson Hyperlegible bold */ +@font-face { + font-family: "Atkinson Hyperlegible"; + src: url("./fonts/Atkinson-Hyperlegible-Bold-102a.woff2") format('woff2'); + font-weight: bold; + font-style: normal; +} + +/* Atkinson Hyperlegible italic */ +@font-face { + font-family: "Atkinson Hyperlegible"; + src: url("./fonts/Atkinson-Hyperlegible-Italic-102a.woff2") format('woff2'); + font-weight: normal; + font-style: italic; +} + +/* Atkinson Hyperlegible bold italic */ +@font-face { + font-family: "Atkinson Hyperlegible"; + src: url("./fonts/Atkinson-Hyperlegible-BoldItalic-102a.woff2") format('woff2'); + font-weight: bold; + font-style: italic; +} diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..4bb9236 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,64 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'GMT Examples' +copyright = '2022, The GMT Examples Authors' +author = 'GMT Examples Contributors' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autosectionlabel", + "sphinx.ext.extlinks", + "sphinx_gmt.gmtplot", +] +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# configure links to GMT docs +extlinks = { + "gmt-module": ("https://docs.generic-mapping-tools.org/latest/%s", "%s"), +} + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# 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_favicon = "_static/favicon.png" +html_static_path = ["_static"] +html_css_files = ["style.css"] + +# Adjust highlight language for sphinx_gmt examples +highlight_language = "bash" diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..d0d3947 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,141 @@ +Contributors Guide +------------------ + +This is a community driven project and everyone is welcome to contribute. The +project is hosted at the `gmt-examples GitHub repository `_. + +The goal is to maintain a diverse community that's pleasant for everyone. +**Please be considerate and respectful of others**. Everyone must abide by our +`Code of Conduct `_ +and we encourage all to read it carefully. + +GMT Examples Overview +~~~~~~~~~~~~~~~~~~~~~ + +There are two main components to GMT examples project: + +* Gallery examples, with source material in the ``docs/gallery/`` folder. +* Tutorial examples, with source material in the ``docs/tutorials/`` folder. + +The gallery examples are designed to instruct users on how to complete a specific +problem. For general recommendations on how to design effective gallery examples, +see the `diataxis framework's section on how-to guides `_. + +The tutorials are learning orientated with the goal of teaching users GMT. For +general recommendations on how to design effective tutorials, see the +`diataxis framework's section on tutorials `_. + +The documentation are written primarily in +`reStructuredText `_ and built by +`Sphinx `_. Please refer to +`reStructuredText Cheatsheet `_ +if you are new to reStructuredText. + +Setting up your environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following dependencies are required for building the GMT examples pages: + +- `gmt `_ (GMT is required for executing example scripts) +- `sphinx `_ (a Python documentation generator for creating the docs from source files) +- `sphinx_gmt `_ (a Sphinx extension for creating GMT figures to accompany example scripts) +- `sphinx_rtd_theme `_ (a Sphinx theme used for consistent documentation appearance between GMT projects) + +Two options for installing the dependencies are :ref:`pip ` and :ref:`conda `. +Since Sphinx is a Python documentation generator, you will need a working Python +environment. For those who do not already have a working Python environment, +one option is to use the minimal installer for Conda `Miniforge `_ +along with the :ref:`conda ` instructions. + +Pip Setup +^^^^^^^^^ + +These instructions rely on the `pip `_ package +installer, which can be used to install all dependencies except GMT. +Follow the `GMT Install Guide `_ +to install GMT. The Python dependencies can be installed using the +``requirements.txt`` from the base of the repository (you may wish to setup a +`virtual environment `_ first): + +Unix/macOS:: + + python -m pip install -r requirements.txt + +Windows:: + + py -m pip install -r requirements.txt + +Conda Setup +^^^^^^^^^^^ + +These instructions rely on the `conda `_ package +manager. Run the following from the base of the repository to create a new conda +environment from the ``environment.yml`` file:: + + conda env create + +Before building the documentation, you have to activate the environment +(you'll need to do this every time you start a new terminal):: + + conda activate gmt-examples + +Building the documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once you have :ref:`setup your environment `, you can +build the documentation using:: + + cd docs + make html + +Contributing New Examples +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The source files for the gallery examples and tutorials are ``.rst`` files in +``docs/`` that generate one or more figures using the +`sphinx_gmt `_ +extension. To add a new gallery example or tutorial: + +* If necessary, create a new sub-directory under ``docs/gallery/`` for a + gallery example section (e.g., ``basemaps/`` or ``plot_embellishments/``). +* Create a new ``.rst`` file inside the appropriate sub-directory in + ``docs/gallery/`` or ``docs/tutorials/``. +* Add a descriptive title and as much explanation as necessary. +* Add hyperlinks to GMT modules using the ``gmt-module`` reStructuredText directive:: + + :gmt-module:`grdview` + +* Add hyperlinks to GMT module options by appending lower-case ``#