Merge pull request #26 from csdms/mdpiper/update-docs-build

Update docs build
csdms · Mar 28, 2024 · b932729 · b932729
2 parents abf42fa + d35a93f
commit b932729
Show file tree

Hide file tree

Showing 14 changed files with 157 additions and 101 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,63 +1,53 @@
-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)
 - Move metadata from setup.cfg to pyproject.toml (#14)
 - 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

diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,3 @@
+sphinx
+recommonmark
+pandoc
diff --git a/docs/source/CHANGES.rst 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
@@ -0,0 +1,6 @@
+Code of Conduct
+===============
+
+Everyone participating in this project is governed by the CSDMS `Code of
+Conduct <https://github.com/csdms/project/blob/main/CODE-OF-CONDUCT.md>`__.
+By participating, you are expected to uphold this code.
diff --git a/docs/source/CONTRIBUTING.rst b/docs/source/CONTRIBUTING.rst
@@ -0,0 +1,8 @@
+Contributing
+============
+
+We welcome, and greatly appreciate, contributions to `CSDMS
+Workbench <https://csdms.colorado.edu/wiki/Workbench>`__ tools. For
+recommendations on how you can contribute, please see the CSDMS project
+`CONTRIBUTING <https://github.com/csdms/project/blob/main/CONTRIBUTING.md>`__
+document.
diff --git a/docs/source/LICENSE.rst 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
@@ -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/changelog.rst b/docs/source/changelog.rst
diff --git 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 <https://nsf.gov/awardsearch/showAward?AWD_ID=1831623>`_,
 *Community Facility Support: The Community Surface Dynamics Modeling System (CSDMS)*.
-
-Indices and tables
-------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/source/license.rst b/docs/source/license.rst
diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt
diff --git 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