Skip to content

Commit

Permalink
Change to build document to deploy to ReadTheDocs.org (#76)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
wh3248 authored Nov 17, 2023
1 parent 3fa4547 commit ca98b0f
Show file tree
Hide file tree
Showing 35 changed files with 70 additions and 30 deletions.
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
23 changes: 23 additions & 0 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
@@ -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

22 changes: 0 additions & 22 deletions build_docs/build.sh

This file was deleted.

3 changes: 2 additions & 1 deletion build_docs/Makefile → docs/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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 = .

Expand Down
2 changes: 1 addition & 1 deletion build_docs/generate_docs.py → docs/generate_docs.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
10 changes: 6 additions & 4 deletions build_docs/source/conf.py → docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)))
Expand All @@ -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 -------------------------------------------------

Expand All @@ -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)
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
7 changes: 7 additions & 0 deletions docs/source/hf_hydrodata.data_model_access.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
hf\_hydrodata.data\_model\_access module
========================================

.. automodule:: hf_hydrodata.data_model_access
:members:
:undoc-members:
:show-inheritance:
7 changes: 7 additions & 0 deletions docs/source/hf_hydrodata.generate_hydrodata_catalog_yaml.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
hf\_hydrodata.generate\_hydrodata\_catalog\_yaml module
=======================================================

.. automodule:: hf_hydrodata.generate_hydrodata_catalog_yaml
:members:
:undoc-members:
:show-inheritance:
File renamed without changes.
File renamed without changes.
File renamed without changes.
7 changes: 7 additions & 0 deletions docs/source/hf_hydrodata.projection.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
hf\_hydrodata.projection module
===============================

.. automodule:: hf_hydrodata.projection
:members:
:undoc-members:
:show-inheritance:
Original file line number Diff line number Diff line change
Expand Up @@ -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
---------------
Expand Down
File renamed without changes.
7 changes: 7 additions & 0 deletions docs/source/modules.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
src
===

.. toctree::
:maxdepth: 4

hf_hydrodata
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand Down

0 comments on commit ca98b0f

Please sign in to comment.