From d78a854dad7789118258eaaa35f0acbde85a299b Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 28 Mar 2024 11:23:23 -0600 Subject: [PATCH 1/5] Use Markdown headings in changelog --- CHANGES.md | 26 ++++++++------------------ 1 file changed, 8 insertions(+), 18 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 71ba966..d15c873 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,28 +1,23 @@ -Changes for bmi-geotiff -======================= +# Changes for bmi-geotiff ## 0.3.3 (unreleased) ---------------------- - Nothing changed yet. ## 0.3.2 (2024-03-22) ------------------- - Test with Python 3.12 (#25) - Link to project contributing and code of conduct docs (#23) - Update citation file to cff 1.2.0 -0.3.1 (2023-08-28) ------------------- +## 0.3.1 (2023-08-28) - Update build and test process (#19) -0.3 (2022-08-04) ----------------- +## 0.3 (2022-08-04) - Fix source and binary distributions (#17) - Switch from xarray to rioxarray (#15) @@ -30,34 +25,29 @@ Changes for bmi-geotiff - Use CITATION.cff file (#8) -0.2.3 (2021-05-09) ------------------- +## 0.2.3 (2021-05-09) - Modify how the BMI treats the projection string variable (#7) -0.2.2 (2021-05-05) ------------------- +## 0.2.2 (2021-05-05) - Fix shapes in BMI (#6) -0.2.1 (2021-05-05) ------------------- +## 0.2.1 (2021-05-05) - Add DOI and CITATION document - Remove dimensions of length 1 (#5) -0.2 (2021-04-22) ----------------- +## 0.2 (2021-04-22) - Add user and API documentation, deplot to Read the Docs (#3) - Set up CI tasks using GitHub Actions (#4) -0.1 (2021-04-16) ----------------- +## 0.1 (2021-04-16) - Create base library that uses xarray - Write tests for library From 6484a452249c09ee0f9fb8168f69e53f944865c5 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 28 Mar 2024 11:32:26 -0600 Subject: [PATCH 2/5] Remove obsolete docs Makefiles --- docs/Makefile | 20 -------------------- docs/make.bat | 35 ----------------------------------- 2 files changed, 55 deletions(-) delete mode 100644 docs/Makefile delete mode 100644 docs/make.bat diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# 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 = source -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/make.bat b/docs/make.bat deleted file mode 100644 index 6247f7e..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd From ed3430abfff219456b7816a45f96c68fc5dd7c0f Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 28 Mar 2024 11:35:53 -0600 Subject: [PATCH 3/5] Move docs requirements; add requirements from pyproject.toml --- docs/requirements.txt | 3 +++ docs/source/requirements.txt | 1 - 2 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 docs/requirements.txt delete mode 100644 docs/source/requirements.txt diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..d76b099 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx +recommonmark +pandoc diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt deleted file mode 100644 index 6966869..0000000 --- a/docs/source/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -sphinx From c30c6ea32fee8e41bd00fd2750305ed4523a9aa8 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 28 Mar 2024 11:49:44 -0600 Subject: [PATCH 4/5] Use pandoc to create rst-ified versions of project docs The rst versions are created in the docs/ directory and used to build the rst-based docs. --- docs/source/CHANGES.rst | 72 +++++++++++++++++++++++++++++++++ docs/source/CODE-OF-CONDUCT.rst | 6 +++ docs/source/CONTRIBUTING.rst | 8 ++++ docs/source/LICENSE.rst | 23 +++++++++++ docs/source/README.rst | 7 ++-- docs/source/license.rst | 1 - noxfile.py | 19 +++++---- 7 files changed, 123 insertions(+), 13 deletions(-) create mode 100644 docs/source/CHANGES.rst 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/CHANGES.rst b/docs/source/CHANGES.rst new file mode 100644 index 0000000..63e2c00 --- /dev/null +++ b/docs/source/CHANGES.rst @@ -0,0 +1,72 @@ +Changes for bmi-geotiff +======================= + +0.3.3 (unreleased) +------------------ + +- Nothing changed yet. + +0.3.2 (2024-03-22) +------------------ + +- Test with Python 3.12 (#25) +- Link to project contributing and code of conduct docs (#23) +- Update citation file to cff 1.2.0 + +.. _section-1: + +0.3.1 (2023-08-28) +------------------ + +- Update build and test process (#19) + +.. _section-2: + +0.3 (2022-08-04) +---------------- + +- Fix source and binary distributions (#17) +- Switch from xarray to rioxarray (#15) +- Move metadata from setup.cfg to pyproject.toml (#14) +- Use CITATION.cff file (#8) + +.. _section-3: + +0.2.3 (2021-05-09) +------------------ + +- Modify how the BMI treats the projection string variable (#7) + +.. _section-4: + +0.2.2 (2021-05-05) +------------------ + +- Fix shapes in BMI (#6) + +.. _section-5: + +0.2.1 (2021-05-05) +------------------ + +- Add DOI and CITATION document +- Remove dimensions of length 1 (#5) + +.. _section-6: + +0.2 (2021-04-22) +---------------- + +- Add user and API documentation, deplot to Read the Docs (#3) +- Set up CI tasks using GitHub Actions (#4) + +.. _section-7: + +0.1 (2021-04-16) +---------------- + +- Create base library that uses xarray +- Write tests for library +- Implement BMI for GeoTiff class from template generated by + ``bmipy-render`` +- Make demo Jupyter Notebooks 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..e0c6546 --- /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/README.rst b/docs/source/README.rst index 56e191f..35d8cad 100644 --- a/docs/source/README.rst +++ b/docs/source/README.rst @@ -1,5 +1,4 @@ -|Basic Model Interface| |PyPI| |Conda Version| |Build/Test CI| -|Documentation Status| +|DOI| |PyPI| |Conda Version| |Build/Test CI| |Documentation Status| bmi-geotiff =========== @@ -158,8 +157,8 @@ directory of the *bmi-geotiff* repository. Documentation for *bmi-geotiff* is available at https://bmi-geotiff.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.8327418.svg + :target: https://doi.org/10.5281/zenodo.8327418 .. |PyPI| image:: https://img.shields.io/pypi/v/bmi-geotiff :target: https://pypi.org/project/bmi-geotiff .. |Conda Version| image:: https://img.shields.io/conda/vn/conda-forge/bmi-geotiff.svg 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 737f7d9..21f2d67 100644 --- a/noxfile.py +++ b/noxfile.py @@ -67,21 +67,24 @@ 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", "CONTRIBUTING", "CODE-OF-CONDUCT", "LICENSE"]: + session.run( + "pandoc", "--to", "rst", f"{file}.md", "--output", f"docs/source/{file}.rst" + ) -@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(".[docs]") - session.chdir("docs") + session.conda_install("--file", "docs/requirements.txt") + session.install("-e", ".") + + 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 d35a93f826c43ffba82c51068ede0dbc00bc3a9a Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 28 Mar 2024 12:05:44 -0600 Subject: [PATCH 5/5] Reorganize headings in main docs page --- docs/source/changelog.rst | 1 - docs/source/index.rst | 36 +++++++++++++++++++++++------------- 2 files changed, 23 insertions(+), 14 deletions(-) delete mode 100644 docs/source/changelog.rst 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 811a89a..9778bfe 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,27 +2,44 @@ .. 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. .. toctree:: - :maxdepth: 2 + :maxdepth: 4 api/index +Changelog +......... -Additional Information -====================== +.. toctree:: + :maxdepth: 2 + + CHANGES + +Project documents +................. .. toctree:: :maxdepth: 2 - changelog - license + LICENSE + CODE-OF-CONDUCT + CONTRIBUTING + +Indices and tables +.................. + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` Help ---- @@ -36,10 +53,3 @@ Acknowledgments This work is supported by the National Science Foundation under Award No. `1831623 `_, *Community Facility Support: The Community Surface Dynamics Modeling System (CSDMS)*. - -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search`