diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a084db06..c9cb0ae9 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -9,12 +9,12 @@ on: paths: - 'HinetPy/*.py' - 'docs/**' - - 'README.rst' + - 'README.md' pull_request: paths: - 'HinetPy/*.py' - 'docs/**' - - 'README.rst' + - 'README.md' workflow_dispatch: concurrency: @@ -43,7 +43,7 @@ jobs: - name: Install dependencies run: | - python -m pip install build sphinx sphinx-intl sphinx_rtd_theme + python -m pip install build myst-parser sphinx sphinx-intl sphinx_rtd_theme make build python -m pip install dist/*.whl diff --git a/README.md b/README.md new file mode 100644 index 00000000..738d8c89 --- /dev/null +++ b/README.md @@ -0,0 +1,104 @@ +[![Tests](https://github.com/seisman/HinetPy/actions/workflows/tests.yml/badge.svg)](https://github.com/seisman/HinetPy/actions/workflows/tests.yml) +[![codecov](https://codecov.io/gh/seisman/HinetPy/branch/main/graph/badge.svg)](https://codecov.io/gh/seisman/HinetPy) +[![GitHub release](https://img.shields.io/github/release/seisman/HinetPy.svg)](https://github.com/seisman/HinetPy/releases) +[![PyPI version](https://img.shields.io/pypi/v/HinetPy.svg)](https://pypi.org/project/HinetPy/) +[![Python versions](https://img.shields.io/pypi/pyversions/HinetPy.svg)](https://pypi.org/project/HinetPy/) +[![License](https://img.shields.io/github/license/seisman/HinetPy.svg)](https://github.com/seisman/HinetPy/blob/main/LICENSE) +[![JOSS](https://joss.theoj.org/papers/10.21105/joss.06840/status.svg)](https://doi.org/10.21105/joss.06840) +[![Zenodo](https://zenodo.org/badge/23509035.svg)](https://zenodo.org/badge/latestdoi/23509035) + +[NIED Hi-net](https://www.hinet.bosai.go.jp/) | +[Source Code](https://github.com/seisman/HinetPy) | +[Documentation](https://seisman.github.io/HinetPy) | +[中文文档](https://seisman.github.io/HinetPy/zh_CN/) + +--- + + + +[HinetPy](https://github.com/seisman/HinetPy) is a Python package for accessing and +processing seismic data from [NIED Hi-net](https://www.hinet.bosai.go.jp/). + +## Key Features + +- Facilitates easy access to NIED Hi-net seismic data, including continuous/event + waveform data and event catalogs. +- Supports multiple seismic networks (e.g., F-net, S-net, MeSO-net and more in addition + to Hi-net) in Japan. +- Selects a subset of stations based on geographical location or station name (supports + Hi-net, F-net, S-net and MeSO-net only). +- Converts waveform data to SAC format and instrumental responses to SAC polezero files. +- Speeds up the downloading and processing workflow via the use of multithreading. + +## A Simple Example + +Here is an example showing how to use HinetPy to request continuous waveform data from +Hi-net, convert the data into SAC format, and extract instrumental responses as SAC +polezero files. + +```python +from HinetPy import Client, win32 + +# You need a Hi-net account to access the data +client = Client("username", "password") + +# Let's try to request 20-minute data of the Hi-net network (with an internal +# network code of '0101') starting at 2010-01-01T00:00 (JST, GMT+0900) +data, ctable = client.get_continuous_waveform("0101", "201001010000", 20) + +# The request and download process usually takes a few minutes +# waiting for data request ... +# waiting for data download ... + +# Now you can see the data and corresponding channel table in your working directory +# waveform data (in win32 format) : 0101_201001010000_20.cnt +# channel table (plaintext file) : 0101_20100101.ch + +# Let's convert data from win32 format to SAC format +win32.extract_sac(data, ctable) + +# Let's extract instrument response as PZ files from the channel table file +win32.extract_sacpz(ctable) + +# Now you can see several SAC and SAC_PZ files in your working directory + +# N.NGUH.E.SAC N.NGUH.U.SAC N.NNMH.N.SAC +# N.NGUH.N.SAC N.NNMH.E.SAC N.NNMH.U.SAC +# ... +# N.NGUH.E.SAC_PZ N.NGUH.U.SAC_PZ N.NNMH.N.SAC_PZ +# N.NGUH.N.SAC_PZ N.NNMH.E.SAC_PZ N.NNMH.U.SAC_PZ +# ... +``` + +## Citation + +If you find this package useful, please consider citing the package in either of the +following ways: + +**Cite the HinetPy paper (preferred)** + +A formal paper is published in [The Journal of Open Source Software](https://joss.theoj.org/) +since HinetPy v0.9.0. This is the **preferred** way for citation. + +> Tian, D. (2024). HinetPy: A Python package for accessing and processing NIED Hi-net +> seismic data. Journal of Open Source Software, 9(98), 6840. +> https://doi.org/10.21105/joss.06840 + +**Cite a specific HinetPy version** + +If you'd like to cite a specific HinetPy version, you can visit +[Zenodo](https://zenodo.org/records/12523911), choose the version you want to cite, +and cite like this: + +> Tian, D. (20XX). HinetPy: A Python package for accessing and processing NIED Hi-net +> seismic data (X.X.X). Zenodo. https://doi.org/10.5281/zenodo.xxxxxxxx + +## Contributing + +Feedback and contributions are welcome. Please feel free to open an issue or pull +request if you have any suggestions or would like to contribute a feature. +For additional information or specific questions, please open an issue directly. + +## License + +This project is licensed under the terms of the MIT license. diff --git a/README.rst b/README.rst deleted file mode 100644 index fbe749b7..00000000 --- a/README.rst +++ /dev/null @@ -1,117 +0,0 @@ -.. image:: https://github.com/seisman/HinetPy/actions/workflows/tests.yml/badge.svg - :target: https://github.com/seisman/HinetPy/actions/workflows/tests.yml -.. image:: https://codecov.io/gh/seisman/HinetPy/branch/main/graph/badge.svg - :target: https://codecov.io/gh/seisman/HinetPy -.. image:: https://img.shields.io/github/release/seisman/HinetPy.svg - :target: https://github.com/seisman/HinetPy/releases -.. image:: https://img.shields.io/pypi/v/HinetPy.svg - :target: https://pypi.org/project/HinetPy/ -.. image:: https://img.shields.io/pypi/pyversions/HinetPy.svg - :target: https://pypi.org/project/HinetPy/ -.. image:: https://img.shields.io/github/license/seisman/HinetPy.svg - :target: https://github.com/seisman/HinetPy/blob/main/LICENSE -.. image:: https://joss.theoj.org/papers/10.21105/joss.06840/status.svg - :target: https://doi.org/10.21105/joss.06840 -.. image:: https://zenodo.org/badge/23509035.svg - :target: https://zenodo.org/badge/latestdoi/23509035 - - -`NIED Hi-net `__ | -`Source Code `__ | -`Documentation `__ | -`中文文档 `__ - ----- - -.. placeholder-for-doc-index - -`HinetPy `_ is a Python package for accessing and -processing seismic data from `NIED Hi-net `__. - -Key Features -============ - -- Facilitates easy access to NIED Hi-net seismic data, including continuous/event - waveform data and event catalogs. -- Supports multiple seismic networks (e.g., F-net, S-net, MeSO-net and more in addition - to Hi-net) in Japan. -- Selects a subset of stations based on geographical location or station name (Supports - Hi-net, F-net, S-net and MeSO-net only). -- Converts waveform data to SAC format and instrumental responses to SAC polezero files. -- Speeds up the downloading and processing workflow via the use of multithreading. - -A simple example -================ - -Here is an example showing how to use HinetPy to request continuous waveform data from -Hi-net, convert the data into SAC format, and extract instrumental responses as SAC -polezero files. - -.. code-block:: python - - from HinetPy import Client, win32 - - # You need a Hi-net account to access the data - client = Client("username", "password") - - # Let's try to request 20-minute data of the Hi-net network (with an internal - # network code of '0101') starting at 2010-01-01T00:00 (JST, GMT+0900) - data, ctable = client.get_continuous_waveform("0101", "201001010000", 20) - - # The request and download process usually takes a few minutes - # waiting for data request ... - # waiting for data download ... - - # Now you can see the data and corresponding channel table in your working directory - # waveform data (in win32 format) : 0101_201001010000_20.cnt - # channel table (plaintext file) : 0101_20100101.ch - - # Let's convert data from win32 format to SAC format - win32.extract_sac(data, ctable) - - # Let's extract instrument response as PZ files from the channel table file - win32.extract_sacpz(ctable) - - # Now you can see several SAC and SAC_PZ files in your working directory - - # N.NGUH.E.SAC N.NGUH.U.SAC N.NNMH.N.SAC - # N.NGUH.N.SAC N.NNMH.E.SAC N.NNMH.U.SAC - # ... - # N.NGUH.E.SAC_PZ N.NGUH.U.SAC_PZ N.NNMH.N.SAC_PZ - # N.NGUH.N.SAC_PZ N.NNMH.E.SAC_PZ N.NNMH.U.SAC_PZ - # ... - -Citation -======== - -If you find this package useful, please consider citing the package in either of the -following ways: - -**Cite the HinetPy paper (preferred)** - -A formal paper is published on `The Journal of Open Source Software `__ -since HinetPy v0.9.0. This is the **preferred** way for citation. - - Tian, D. (2024). HinetPy: A Python package for accessing and processing NIED Hi-net seismic data. - Journal of Open Source Software, 9(98), 6840. https://doi.org/10.21105/joss.06840 - -**Cite a specific HinetPy version** - -If you'd like to cite a specific HinetPy version, you can visit -`Zenodo `__, choose the version you want to cite, -and cite like this: - - Tian, D. (20XX). HinetPy: A Python package for accessing and processing NIED Hi-net seismic data (X.X.X). - Zenodo. https://doi.org/10.5281/zenodo.xxxxxxxx - -Contributing -============ - -Feedback and contributions are welcome! Please feel free to open an issue or pull -request if you have any suggestions or would like to contribute a feature. -For additional information or specific questions, please open an issue directly. - -License -======= - -This project is licensed under the terms of the MIT license. diff --git a/docs/conf.py b/docs/conf.py index a8f05053..16fb0f28 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -39,6 +39,7 @@ "sphinx.ext.githubpages", "sphinx.ext.intersphinx", "sphinx.ext.napoleon", + "myst_parser", "sphinx_rtd_theme", ] diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..bff26647 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,18 @@ +# HinetPy + +```{toctree} +:maxdepth: 1 +:hidden: + +installation +tutorial +examples +api +appendix +changelog +license +``` + +```{include} ../README.md +:start-after: +``` diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 62840190..00000000 --- a/docs/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -HinetPy -======= - -.. toctree:: - :maxdepth: 1 - :hidden: - - installation - tutorial - examples - api - appendix - changelog - license - -.. include:: ../README.rst - :start-after: placeholder-for-doc-index diff --git a/docs/locale/zh_CN/LC_MESSAGES/index.po b/docs/locale/zh_CN/LC_MESSAGES/index.po index 424aeca1..96ea6443 100644 --- a/docs/locale/zh_CN/LC_MESSAGES/index.po +++ b/docs/locale/zh_CN/LC_MESSAGES/index.po @@ -16,11 +16,11 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 2.13.1\n" -#: ../../index.rst:2 +#: ../../index.md:1 msgid "HinetPy" msgstr "" -#: ../../../README.rst:3 +#: ../../../README.md:16 msgid "" "`HinetPy `_ is a Python package for " "accessing and processing seismic data from `NIED Hi-net " @@ -29,66 +29,66 @@ msgstr "" "`HinetPy `_ 是一个可用于申请和处理 `NIED Hi-net " "`__ 地震数据的 Python 包。" -#: ../../../README.rst:7 +#: ../../../README.md:19 msgid "Key Features" msgstr "主要功能" -#: ../../../README.rst:9 +#: ../../../README.md:21 msgid "" "Facilitates easy access to NIED Hi-net seismic data, including " "continuous/event waveform data and event catalogs." msgstr "方便访问 NIED Hi-net 地震数据，包括连续/事件波形数据和事件目录。" -#: ../../../README.rst:11 +#: ../../../README.md:23 msgid "" "Supports multiple seismic networks (e.g., F-net, S-net, MeSO-net and more" " in addition to Hi-net) in Japan." msgstr "支持日本多个地震台网（如 Hi-net、F-net、S-net、MeSO-net 等）。" -#: ../../../README.rst:13 +#: ../../../README.md:25 msgid "" "Selects a subset of stations based on geographical location or station " "name (Supports Hi-net, F-net, S-net and MeSO-net only)." msgstr "根据地理位置或台站名称选择台站子集（仅支持 Hi-net、F-net、S-net 和 MeSO-net）。" -#: ../../../README.rst:15 +#: ../../../README.md:27 msgid "" "Converts waveform data to SAC format and instrumental responses to SAC " "polezero files." msgstr "将波形数据转换为 SAC 格式，将仪器响应转换为 SAC 极零文件。" -#: ../../../README.rst:16 +#: ../../../README.md:28 msgid "" "Speeds up the downloading and processing workflow via the use of " "multithreading." msgstr "通过使用多线程，加快下载和处理工作流程。" -#: ../../../README.rst:19 +#: ../../../README.md:30 msgid "A simple example" msgstr "一个简单的示例" -#: ../../../README.rst:21 +#: ../../../README.md:32 msgid "" "Here is an example showing how to use HinetPy to request continuous " "waveform data from Hi-net, convert the data into SAC format, and extract " "instrumental responses as SAC polezero files." msgstr "下面的示例展示了如何使用 HinetPy 从 Hi-net 申请连续波形数据，将数据转换为 SAC 格式，并提取 SAC 零极点格式的仪器响应文件。" -#: ../../../README.rst:60 +#: ../../../README.md:72 msgid "Citation" msgstr "引用" -#: ../../../README.rst:62 +#: ../../../README.md:74 msgid "" "If you find this package useful, please consider cite the package in " "either of the following ways:" msgstr "如果你觉得这个软件包很有用，请考虑通过如下方式中的任一种引用该软件：" -#: ../../../README.rst:65 +#: ../../../README.md:77 msgid "**Cite the HinetPy paper (preferred)**" msgstr "**引用 HinetPy 的文章（推荐）**" -#: ../../../README.rst:67 +#: ../../../README.md:79 msgid "" "A formal paper is published on `The Journal of Open Source Software " "`__ since HinetPy v0.9.0. This is the " @@ -96,18 +96,18 @@ msgid "" msgstr "自 HinetPy v0.9.0 起，HinetPy 的介绍文章发表在 `The Journal of Open Source Software " "`__ 上。这是首选的引用方式。" -#: ../../../README.rst:70 +#: ../../../README.md:83 msgid "" "Tian, D. (2024). HinetPy: A Python package for accessing and processing " "NIED Hi-net seismic data. Journal of Open Source Software, 9(98), 6840. " "https://doi.org/10.21105/joss.06840" msgstr "" -#: ../../../README.rst:73 +#: ../../../README.md:87 msgid "**Cite a specific HinetPy version**" msgstr "**引用特定的 HinetPy 版本**" -#: ../../../README.rst:75 +#: ../../../README.md:89 msgid "" "If you'd like to cite a specific HinetPy version, you can visit `Zenodo " "`__, choose the version you want to " @@ -115,18 +115,18 @@ msgid "" msgstr "如果想引用特定的 HinetPy 版本，可以访问 `Zenodo `__，" "选择要引用的版本，然后像这样引用：" -#: ../../../README.rst:79 +#: ../../../README.md:94 msgid "" "Tian, D. (20XX). HinetPy: A Python package for accessing and processing " "NIED Hi-net seismic data (X.X.X). Zenodo. " "https://doi.org/10.5281/zenodo.xxxxxxxx" msgstr "" -#: ../../../README.rst:83 +#: ../../../README.md:97 msgid "Contributing" msgstr "贡献指南" -#: ../../../README.rst:85 +#: ../../../README.md:99 msgid "" "Feedback and contributions are welcome! Please feel free to open an issue" " or pull request if you have any suggestions or would like to contribute " @@ -135,10 +135,10 @@ msgid "" msgstr "欢迎反馈和贡献！如果您有任何建议或想贡献一项功能，请新建一个 issue 或 pull request。" "如需其他信息或具体问题，请直接提交 issue。" -#: ../../../README.rst:90 +#: ../../../README.md:104 msgid "License" msgstr "许可协议" -#: ../../../README.rst:92 +#: ../../../README.md:106 msgid "This project is licensed under the terms of the MIT license." msgstr "本项目使用 MIT 许可协议。" diff --git a/pyproject.toml b/pyproject.toml index 6e9d7cac..9a4dd308 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta" [project] name = "HinetPy" description = "A Python package for accessing and processing NIED Hi-net seismic data" -readme = "README.rst" +readme = "README.md" requires-python = ">=3.9" authors = [{name = "Dongdong Tian", email = "seisman.info@gmail.com"}] license = "MIT"