Change to build document to deploy to ReadTheDocs.org (#76)

* move rtd to docs folder * update version * update .readthedocs.yaml * fix requirements.txt path * fix yaml * fix generate_docs.py to write to source dir * validate_data_model in doc gen * add back moved message
hydroframe · Nov 17, 2023 · ca98b0f · ca98b0f
1 parent 3fa4547
commit ca98b0f
Show file tree

Hide file tree

Showing 35 changed files with 70 additions and 30 deletions.
diff --git a/.gitignore b/.gitignore
@@ -3,8 +3,13 @@ __pycache__/
 *.py[cod]
 *$py.class
 **/*.bkp
+**/*.swp
 build_docs/source/bin
 deploy_docs
+docs/source/gen_*
+docs/html
+docs/doctrees
+docs/source/bin
 
 # C extensions
 *.so

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,23 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: requirements.txt
+
diff --git a/build_docs/build.sh b/build_docs/build.sh
diff --git a/build_docs/Makefile → docs/Makefile b/build_docs/Makefile → docs/Makefile
@@ -3,7 +3,8 @@
 # You can set these variables from the command line.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SPHINXPROJ    = hydroframe
+SPHINXAPIDOC = ?= spinx-apidoc
+SPHINXPROJ    = hf_hydroframe
 SOURCEDIR     = source
 BUILDDIR      = .
 

diff --git a/build_docs/generate_docs.py → docs/generate_docs.py b/build_docs/generate_docs.py → docs/generate_docs.py
@@ -23,7 +23,7 @@ def main():
 def generate_datasets():
     """Generate the documentation of datasets (not used now)"""
 
-    directory = "./source"
+    directory = os.path.abspath(os.path.join(os.path.dirname(__file__), "source"))
     (dataset_type_ids, dataset_ids) = _collect_visible_datasets()
 
     gen_dataset_list_path = f"{directory}/gen_dataset_list.rst"

diff --git a/docs/index.html b/docs/index.html
@@ -2,6 +2,6 @@
     <body>
         <h1>Web Site Moved!</h1>
         <p>The new Read-The-Docs Page for hf_hydrodata is now at:</p>
-        <p style="margin-left:10px"><a href="https://maurice.princeton.edu/hydroframe/docs">https://maurice.princeton.edu/hydroframe/docs</a></p>
+        <p style="margin-left:10px"><a href="https://hf-hydrodata.readthedocs.io">https://hf-hydrodata.readthedocs.io</a></p>
     </body>
 </html>
diff --git a/build_docs/make.bat → docs/make.bat b/build_docs/make.bat → docs/make.bat
diff --git a/build_docs/source/_static/css/custom.css → docs/source/_static/css/custom.css b/build_docs/source/_static/css/custom.css → docs/source/_static/css/custom.css
diff --git a/build_docs/source/api_reference.rst → docs/source/api_reference.rst b/build_docs/source/api_reference.rst → docs/source/api_reference.rst
diff --git a/build_docs/source/available_data.rst → docs/source/available_data.rst b/build_docs/source/available_data.rst → docs/source/available_data.rst
diff --git a/build_docs/source/conf.py → docs/source/conf.py b/build_docs/source/conf.py → docs/source/conf.py
@@ -11,9 +11,9 @@
 from inspect import getsourcefile
 import pypandoc
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "../src")))
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "../src", "hydroframe")))
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(
-    __file__), "..", "../src", "hydroframe", "data_catalog")))
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+import generate_docs
+import validate_data_model
 
 # Get path to directory containing this file, conf.py.
 DOCS_DIRECTORY = os.path.dirname(os.path.abspath(getsourcefile(lambda: 0)))
@@ -39,7 +39,7 @@
 # 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"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "*data_model_access*", "*projection.*", "*generate_hydrodata_catalog_yaml.*"]
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -64,5 +64,7 @@ def ensure_pandoc_installed(_):
     )
 
 def setup(app):
+    validate_data_model.main()
+    generate_docs.main()
     app.add_css_file("css/custom.css")
     app.connect("builder-inited", ensure_pandoc_installed)
diff --git a/...ource/examples/example_explore_data.ipynb → ...ource/examples/example_explore_data.ipynb b/...ource/examples/example_explore_data.ipynb → ...ource/examples/example_explore_data.ipynb
diff --git a/...cs/source/examples/example_get_data.ipynb → docs/source/examples/example_get_data.ipynb b/...cs/source/examples/example_get_data.ipynb → docs/source/examples/example_get_data.ipynb
diff --git a/...s/source/examples/example_plot_data.ipynb → docs/source/examples/example_plot_data.ipynb b/...s/source/examples/example_plot_data.ipynb → docs/source/examples/example_plot_data.ipynb
diff --git a/...s/source/examples/example_shapefile.ipynb → docs/source/examples/example_shapefile.ipynb b/...s/source/examples/example_shapefile.ipynb → docs/source/examples/example_shapefile.ipynb
diff --git a/build_docs/source/examples/index.rst → docs/source/examples/index.rst b/build_docs/source/examples/index.rst → docs/source/examples/index.rst
diff --git a/build_docs/source/getting_started.rst → docs/source/getting_started.rst b/build_docs/source/getting_started.rst → docs/source/getting_started.rst
diff --git a/build_docs/source/gridded_data/index.rst → docs/source/gridded_data/index.rst b/build_docs/source/gridded_data/index.rst → docs/source/gridded_data/index.rst
diff --git a/docs/source/hf_hydrodata.data_model_access.rst b/docs/source/hf_hydrodata.data_model_access.rst
@@ -0,0 +1,7 @@
+hf\_hydrodata.data\_model\_access module
+========================================
+
+.. automodule:: hf_hydrodata.data_model_access
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/hf_hydrodata.generate_hydrodata_catalog_yaml.rst b/docs/source/hf_hydrodata.generate_hydrodata_catalog_yaml.rst
@@ -0,0 +1,7 @@
+hf\_hydrodata.generate\_hydrodata\_catalog\_yaml module
+=======================================================
+
+.. automodule:: hf_hydrodata.generate_hydrodata_catalog_yaml
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/build_docs/source/hf_hydrodata.grid.rst → docs/source/hf_hydrodata.grid.rst b/build_docs/source/hf_hydrodata.grid.rst → docs/source/hf_hydrodata.grid.rst
diff --git a/build_docs/source/hf_hydrodata.gridded.rst → docs/source/hf_hydrodata.gridded.rst b/build_docs/source/hf_hydrodata.gridded.rst → docs/source/hf_hydrodata.gridded.rst
diff --git a/build_docs/source/hf_hydrodata.point.rst → docs/source/hf_hydrodata.point.rst b/build_docs/source/hf_hydrodata.point.rst → docs/source/hf_hydrodata.point.rst
diff --git a/docs/source/hf_hydrodata.projection.rst b/docs/source/hf_hydrodata.projection.rst
@@ -0,0 +1,7 @@
+hf\_hydrodata.projection module
+===============================
+
+.. automodule:: hf_hydrodata.projection
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/build_docs/source/hf_hydrodata.rst → docs/source/hf_hydrodata.rst b/build_docs/source/hf_hydrodata.rst → docs/source/hf_hydrodata.rst
@@ -7,9 +7,12 @@ Submodules
 .. toctree::
    :maxdepth: 4
 
+   hf_hydrodata.data_model_access
+   hf_hydrodata.generate_hydrodata_catalog_yaml
    hf_hydrodata.grid
    hf_hydrodata.gridded
    hf_hydrodata.point
+   hf_hydrodata.projection
 
 Module contents
 ---------------

diff --git a/build_docs/source/index.rst → docs/source/index.rst b/build_docs/source/index.rst → docs/source/index.rst
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
@@ -0,0 +1,7 @@
+src
+===
+
+.. toctree::
+   :maxdepth: 4
+
+   hf_hydrodata
diff --git a/...ocs/source/point_data/data_collection.rst → docs/source/point_data/data_collection.rst b/...ocs/source/point_data/data_collection.rst → docs/source/point_data/data_collection.rst
diff --git a/build_docs/source/point_data/index.rst → docs/source/point_data/index.rst b/build_docs/source/point_data/index.rst → docs/source/point_data/index.rst
diff --git a/...ource/point_data/metadata_definitions.rst → ...ource/point_data/metadata_definitions.rst b/...ource/point_data/metadata_definitions.rst → ...ource/point_data/metadata_definitions.rst
diff --git a/...d_docs/source/point_data/point_inputs.rst → docs/source/point_data/point_inputs.rst b/...d_docs/source/point_data/point_inputs.rst → docs/source/point_data/point_inputs.rst
diff --git a/..._docs/source/point_data/point_methods.rst → docs/source/point_data/point_methods.rst b/..._docs/source/point_data/point_methods.rst → docs/source/point_data/point_methods.rst
diff --git a/build_docs/source/quickstart.rst → docs/source/quickstart.rst b/build_docs/source/quickstart.rst → docs/source/quickstart.rst
diff --git a/build_docs/validate_data_model.py → docs/validate_data_model.py b/build_docs/validate_data_model.py → docs/validate_data_model.py
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "hf_hydrodata"
-version = "0.9.36"
+version = "0.9.37"
 description = "hydroframe tools and utilities"
 authors = ["William M. Hasling", "Laura Condon", "Reed Maxwell",  "George Artavanis", "Amy M. Johnson", "Amy C. Defnet"]
 license = "MIT"