From af688d449b68d78520f5d3581d33447e5633dc24 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 27 Mar 2024 11:32:11 -0600 Subject: [PATCH 1/8] Update changelog --- CHANGES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES.md b/CHANGES.md index ed43aba..07a1a8f 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,6 +2,7 @@ ## 0.8.4 (unreleased) +- Set minimum python>=3.10 (#67) - Link to project contributing and code of conduct docs (#65) From cd778b4339d1d60618613c6bf5e507fbeddf3cac Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 27 Mar 2024 12:21:43 -0600 Subject: [PATCH 2/8] Convert changelog to rst for docs --- noxfile.py | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/noxfile.py b/noxfile.py index 4e94e1c..ce48098 100644 --- a/noxfile.py +++ b/noxfile.py @@ -75,21 +75,20 @@ def format(session: nox.Session) -> None: @nox.session(name="prepare-docs") def prepare_docs(session: nox.Session) -> None: """Update docs source before building.""" - session.install(".[docs]") session.run("sphinx-apidoc", "-f", "-o", "docs/source/api", PACKAGE) - session.run( - "pandoc", "--to", "rst", "README.md", "--output", "docs/source/README.rst" - ) - + for file in ["README", "CHANGES"]: + session.run( + "pandoc", "--to", "rst", f"{file}.md", "--output", f"docs/source/{file}.rst" + ) @nox.session(name="build-docs") def build_docs(session: nox.Session) -> None: """Build the docs.""" session.install(".[docs]") - session.chdir("docs") + prepare_docs(session) if os.path.exists("build"): shutil.rmtree("build") - session.run("sphinx-build", "-b", "html", "-W", "source", "build/html") + session.run("sphinx-build", "-b", "html", "-W", "docs/source", "build/html") @nox.session From 172eb252b78c86798931ab2303b6e8557f4a5e98 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 27 Mar 2024 12:22:31 -0600 Subject: [PATCH 3/8] Update docs for rst-ified changelog --- docs/source/CHANGES.rst | 146 ++++++++++++++++++++++++++++++++++++++ docs/source/README.rst | 8 +-- docs/source/changelog.rst | 1 - docs/source/index.rst | 2 +- 4 files changed, 151 insertions(+), 6 deletions(-) create mode 100644 docs/source/CHANGES.rst delete mode 100644 docs/source/changelog.rst diff --git a/docs/source/CHANGES.rst b/docs/source/CHANGES.rst new file mode 100644 index 0000000..413953e --- /dev/null +++ b/docs/source/CHANGES.rst @@ -0,0 +1,146 @@ +Changes for bmi-topography +========================== + +0.8.4 (unreleased) +------------------ + +- Set minimum python>=3.10 (#67) +- Link to project contributing and code of conduct docs (#65) + +0.8.3 (2023-12-18) +------------------ + +- Build and test with Python 3.12 (#60) +- Remove setuptools files in favor of pyproject.toml (#59) +- Fix failing docs build (#58) +- Use nox in CI testing (#54) + +.. _section-1: + +0.8.2 (2023-02-06) +------------------ + +- Fix problem getting CRS info for AAIGrid type (#53) + +.. _section-2: + +0.8.1 (2023-01-27) +------------------ + +- Run test CI on Windows with Python 3.10 (#52) +- Use nox instead of make for building and testing project (#51) +- Update project metadata files (#50) +- Use rio accessor for geospatial information (#47) +- Update contents of source and binary distributions (#46) + +.. _section-3: + +0.8 (2022-07-05) +---------------- + +- Switch from xarray to rioxarray (#45) +- Move metadata from setup.cfg to pyproject.toml (#44) + +.. _section-4: + +0.7.1 (2022-06-03) +------------------ + +- Provide a better reason for 401 errors (#41) + +.. _section-5: + +0.7 (2022-03-24) +---------------- + +- Support all OpenTopography global datasets (#39) +- Create test matrix of datasets and file types (#38) + +.. _section-6: + +0.6 (2022-02-17) +---------------- + +- Use dashes in command line options (#36) +- Use a demo API key if a user key can’t be found (#34) + +.. _section-7: + +0.5.1 (2022-02-15) +------------------ + +- Document use of OpenTopography API key (#33) +- Add text to exception raised when API key is missing (#32) +- Use new black syntax (#31) + +.. _section-8: + +0.5 (2022-01-25) +---------------- + +- Use an API key when requesting OpenTopography data (#25) +- Add python 3.10 to tests (#24) +- Address technical debt (#22) + +.. _section-9: + +0.4 (2021-09-03) +---------------- + +- Support ALOS World 3D 30m products (#13) +- Support .asc and .img files (#14) +- Add format job to CI +- Use CITATION.cff file + +.. _section-10: + +0.3.2 (2021-04-23) +------------------ + +- Add citation recommendation with DOI +- Fix typos, update text in example notebooks +- Create CREDITS.md and rearrange docs + +.. _section-11: + +0.3.1 (2021-03-04) +------------------ + +- Install with conda +- Include shell script demonstrating CLI + +.. _section-12: + +0.3 (2021-02-25) +---------------- + +- Update README with overview and install instructions +- Write documentation + +.. _section-13: + +0.2 (2021-02-24) +---------------- + +- Implement BMI for Topography class from template generated by + ``bmipy-render`` +- Include sample config file and Jupyter Notebook to demo BMI +- Add CI with GitHub Actions + +.. _section-14: + +0.1.1 (2021-02-22) +------------------ + +- Add Makefile rule to test upload to TestPyPI +- Test upload to TestPyPI + +.. _section-15: + +0.1 (2021-02-22) +---------------- + +- Create base library that calls OpenTopography API +- Create CLI for library +- Write tests for library and CLI +- Include demo Jupyter Notebook for library diff --git a/docs/source/README.rst b/docs/source/README.rst index f6c2bed..ea54bf5 100644 --- a/docs/source/README.rst +++ b/docs/source/README.rst @@ -1,5 +1,5 @@ -|Basic Model Interface| |Conda Version| |PyPI| |Build/Test CI| |Coverage -Status| |Documentation Status| +|DOI| |Conda Version| |PyPI| |Build/Test CI| |Coverage Status| +|Documentation Status| bmi-topography ============== @@ -220,8 +220,8 @@ https://bmi-topography.readthedocs.io. -.. |Basic Model Interface| image:: https://img.shields.io/badge/CSDMS-Basic%20Model%20Interface-green.svg - :target: https://bmi.readthedocs.io/ +.. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.8327417.svg + :target: https://doi.org/10.5281/zenodo.8327417 .. |Conda Version| image:: https://img.shields.io/conda/vn/conda-forge/bmi-topography.svg :target: https://anaconda.org/conda-forge/bmi-topography .. |PyPI| image:: https://img.shields.io/pypi/v/bmi-topography diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst deleted file mode 100644 index de3cfc7..0000000 --- a/docs/source/changelog.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../CHANGES.md diff --git a/docs/source/index.rst b/docs/source/index.rst index 64aa5cc..aa0bb34 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,7 +21,7 @@ Additional Information .. toctree:: :maxdepth: 2 - changelog + CHANGES license Help From d6bf420d4c51fe5a0ecc662f7bd911f28220d33a Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 27 Mar 2024 12:37:03 -0600 Subject: [PATCH 4/8] Reorganize headings in documentation index page --- docs/source/index.rst | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index aa0bb34..443439f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,9 +2,11 @@ .. include:: README.rst +Additional Information +---------------------- API Reference -============= +............. Looking for information on a particular function, class, or method? This part of the documentation is for you. @@ -14,16 +16,29 @@ This part of the documentation is for you. api/index - -Additional Information -====================== +Changelog +......... .. toctree:: :maxdepth: 2 CHANGES + +Project documents +................. + +.. toctree:: + :maxdepth: 2 + license +Indices and tables +.................. + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + Help ---- @@ -36,10 +51,3 @@ Acknowledgments This work is supported by the National Science Foundation under Award No. `2026951 `_, *EarthCube Capabilities: Cloud-Based Accessible and Reproducible Modeling for Water and Sediment Research*. - -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` From 76db5cad4e966aaa9c1061160d421f006d696456 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 27 Mar 2024 12:45:36 -0600 Subject: [PATCH 5/8] Include project docs in package documentation This includes the license, code of conduct, and contributing docs. --- docs/source/CODE-OF-CONDUCT.rst | 6 ++++++ docs/source/CONTRIBUTING.rst | 8 ++++++++ docs/source/LICENSE.rst | 23 +++++++++++++++++++++++ docs/source/index.rst | 4 +++- docs/source/license.rst | 1 - noxfile.py | 2 +- 6 files changed, 41 insertions(+), 3 deletions(-) create mode 100644 docs/source/CODE-OF-CONDUCT.rst create mode 100644 docs/source/CONTRIBUTING.rst create mode 100644 docs/source/LICENSE.rst delete mode 100644 docs/source/license.rst diff --git a/docs/source/CODE-OF-CONDUCT.rst b/docs/source/CODE-OF-CONDUCT.rst new file mode 100644 index 0000000..528ff21 --- /dev/null +++ b/docs/source/CODE-OF-CONDUCT.rst @@ -0,0 +1,6 @@ +Code of Conduct +=============== + +Everyone participating in this project is governed by the CSDMS `Code of +Conduct `__. +By participating, you are expected to uphold this code. diff --git a/docs/source/CONTRIBUTING.rst b/docs/source/CONTRIBUTING.rst new file mode 100644 index 0000000..081db43 --- /dev/null +++ b/docs/source/CONTRIBUTING.rst @@ -0,0 +1,8 @@ +Contributing +============ + +We welcome, and greatly appreciate, contributions to `CSDMS +Workbench `__ tools. For +recommendations on how you can contribute, please see the CSDMS project +`CONTRIBUTING `__ +document. diff --git a/docs/source/LICENSE.rst b/docs/source/LICENSE.rst new file mode 100644 index 0000000..2a95ee8 --- /dev/null +++ b/docs/source/LICENSE.rst @@ -0,0 +1,23 @@ +MIT License +=========== + +Copyright (c) 2021 Community Surface Dynamics Modeling System + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the +“Software”), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/docs/source/index.rst b/docs/source/index.rst index 443439f..3f022c8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -30,7 +30,9 @@ Project documents .. toctree:: :maxdepth: 2 - license + LICENSE + CODE-OF-CONDUCT + CONTRIBUTING Indices and tables .................. diff --git a/docs/source/license.rst b/docs/source/license.rst deleted file mode 100644 index 356aa9f..0000000 --- a/docs/source/license.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../LICENSE.md diff --git a/noxfile.py b/noxfile.py index ce48098..68f48c6 100644 --- a/noxfile.py +++ b/noxfile.py @@ -76,7 +76,7 @@ def format(session: nox.Session) -> None: def prepare_docs(session: nox.Session) -> None: """Update docs source before building.""" session.run("sphinx-apidoc", "-f", "-o", "docs/source/api", PACKAGE) - for file in ["README", "CHANGES"]: + for file in ["README", "CHANGES", "CONTRIBUTING", "CODE-OF-CONDUCT", "LICENSE"]: session.run( "pandoc", "--to", "rst", f"{file}.md", "--output", f"docs/source/{file}.rst" ) From 64a568045bd4dee22732dfbf43e1c68d34fc9aa1 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 27 Mar 2024 13:24:58 -0600 Subject: [PATCH 6/8] Make pretty --- noxfile.py | 1 + 1 file changed, 1 insertion(+) diff --git a/noxfile.py b/noxfile.py index 68f48c6..6d539ea 100644 --- a/noxfile.py +++ b/noxfile.py @@ -81,6 +81,7 @@ def prepare_docs(session: nox.Session) -> None: "pandoc", "--to", "rst", f"{file}.md", "--output", f"docs/source/{file}.rst" ) + @nox.session(name="build-docs") def build_docs(session: nox.Session) -> None: """Build the docs.""" From 3c7589cfd62f28616bd0291f2cfe4508e55daca8 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 27 Mar 2024 13:56:48 -0600 Subject: [PATCH 7/8] Install docs dependencies from requirements file. For some reason pip install ".[docs]" isn't installing pandoc. I think I've seen this somewhere before. --- docs/{source => }/requirements.txt | 1 + noxfile.py | 5 ++++- 2 files changed, 5 insertions(+), 1 deletion(-) rename docs/{source => }/requirements.txt (74%) diff --git a/docs/source/requirements.txt b/docs/requirements.txt similarity index 74% rename from docs/source/requirements.txt rename to docs/requirements.txt index 085b3a7..d76b099 100644 --- a/docs/source/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ sphinx recommonmark +pandoc diff --git a/noxfile.py b/noxfile.py index 6d539ea..b52a45e 100644 --- a/noxfile.py +++ b/noxfile.py @@ -85,8 +85,11 @@ def prepare_docs(session: nox.Session) -> None: @nox.session(name="build-docs") def build_docs(session: nox.Session) -> None: """Build the docs.""" - session.install(".[docs]") + session.install("-r", "docs/requirements.txt") + session.install("-e", ".") + prepare_docs(session) + if os.path.exists("build"): shutil.rmtree("build") session.run("sphinx-build", "-b", "html", "-W", "docs/source", "build/html") From c02f58ee58a6848a020e3ca07cec0e2c0d0c195b Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 27 Mar 2024 13:59:20 -0600 Subject: [PATCH 8/8] Use a conda backend; install requirements with conda --- noxfile.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/noxfile.py b/noxfile.py index b52a45e..50e6a17 100644 --- a/noxfile.py +++ b/noxfile.py @@ -82,10 +82,10 @@ def prepare_docs(session: nox.Session) -> None: ) -@nox.session(name="build-docs") +@nox.session(name="build-docs", venv_backend="conda") def build_docs(session: nox.Session) -> None: """Build the docs.""" - session.install("-r", "docs/requirements.txt") + session.conda_install("--file", "docs/requirements.txt") session.install("-e", ".") prepare_docs(session)