stac-utils · jonhealy1 · May 30, 2025 · May 30, 2025 · May 30, 2025 · May 30, 2025
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,62 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'docs/**'
+      - 'stac_validator/**/*.py'
+      - 'README.md'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'docs/**'
+      - 'stac_validator/**/*.py'
+      - 'README.md'
+  # Allow manual triggering
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.8'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+        pip install sphinx sphinx_rtd_theme myst-parser sphinx-autodoc-typehints
+    - name: Build documentation
+      run: |
+        sphinx-build -b html docs/ docs/_build/html
+    - name: Upload documentation artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: documentation
+        path: docs/_build/html
+        retention-days: 7
+
+  # Only deploy when pushing to main (not on PRs)
+  deploy:
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download built documentation
+        uses: actions/download-artifact@v4
+        with:
+          name: documentation
+          path: ./docs-build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs-build
+          force_orphan: true
+          commit_message: "Update documentation [skip ci]"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,10 +12,14 @@ The format is (loosely) based on [Keep a Changelog](http://keepachangelog.com/)
 - Added Sponsors and Supporters section to README.md with organizational logos and acknowledgments [#247](https://github.com/stac-utils/stac-validator/pull/247)
 - Added `--pydantic` option for validating STAC objects using stac-pydantic models, providing enhanced type checking and validation [#249](https://github.com/stac-utils/stac-validator/pull/249)
 - Added optional dependency for stac-pydantic that can be installed with `pip install stac-validator[pydantic]` [#249](https://github.com/stac-utils/stac-validator/pull/249)
+- Added GitHub Actions workflow for automatically building and deploying documentation to GitHub Pages [#250](https://github.com/stac-utils/stac-validator/pull/250)
 
 ### Changed
 
 - Reformatted and restructured the README.md for improved readability and organization [#247](https://github.com/stac-utils/stac-validator/pull/247)
+- Migrated documentation from Read the Docs to GitHub Pages for better integration with the repository [#250](https://github.com/stac-utils/stac-validator/pull/250)
+- Updated documentation system to use Sphinx with MyST parser for improved Markdown support [#250](https://github.com/stac-utils/stac-validator/pull/250)
+- Enhanced documentation to include content directly from README.md for consistency [#250](https://github.com/stac-utils/stac-validator/pull/250)
 
 ## [v3.6.0] - 2025-03-25
 

diff --git a/Makefile b/Makefile
@@ -24,3 +24,6 @@ build-tox:		## Test stac_validator on multiple Python versions
 
 run:			## Run the Docker Container and enter into bash
 	docker run -it --entrypoint /bin/bash stac-validator
+
+docs:           ## Build documentation locally
+	sphinx-build -b html -E docs/ docs/_build/html
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 <!-- markdownlint-disable MD033 MD041 -->
 
 <p align="left">
-  <img src="assets/stac-validator.png" width=560>
+  <img src="https://raw.githubusercontent.com/stac-utils/stac-validator/main/assets/stac-validator.png" width=560>
 </p>
 
 [![Downloads](https://static.pepy.tech/badge/stac-validator?color=blue)](https://pepy.tech/project/stac-validator)
@@ -47,7 +47,7 @@ STAC Validator is a tool to validate [STAC (SpatioTemporal Asset Catalog)](https
 
 ## Documentation
 
-For detailed documentation, please visit [read the docs](https://stac-validator.readthedocs.io/en/latest/).
+For detailed documentation, please visit our [GitHub Pages documentation site](https://stac-utils.github.io/stac-validator/).
 
 ## Validate STAC json files against the [STAC spec](https://github.com/radiantearth/stac-spec).
 

diff --git a/docs/_static/STAC-01.png b/docs/_static/STAC-01.png
diff --git a/docs/_static/radiant-earth.webp b/docs/_static/radiant-earth.webp
diff --git a/docs/_static/sparkgeo_logo.jpeg b/docs/_static/sparkgeo_logo.jpeg
diff --git a/docs/_static/stac-validator.png b/docs/_static/stac-validator.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -4,8 +4,6 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-from typing import List
-
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -18,6 +16,9 @@
 
 
 # -- Project information -----------------------------------------------------
+# -- Options for including images from README ----------------------------------
+import os
+import shutil
 
 project = "stac-validator"
 copyright = "2023, Jonathan Healy"
@@ -32,7 +33,14 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions: List[str] = []
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx_rtd_theme",
+    "sphinx.ext.intersphinx",
+    "myst_parser",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -48,9 +56,31 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []
+
+# Create _static directory if it doesn't exist
+static_dir = os.path.join(os.path.dirname(__file__), "_static")
+if not os.path.exists(static_dir):
+    os.makedirs(static_dir)
+
+# Copy assets from project root to _static directory
+assets_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "assets")
+if os.path.exists(assets_dir):
+    for file in os.listdir(assets_dir):
+        src = os.path.join(assets_dir, file)
+        dst = os.path.join(static_dir, file)
+        if os.path.isfile(src):
+            shutil.copy2(src, dst)
+
+# Now that we've copied files, update static path
 html_static_path = ["_static"]
+
+myst_heading_anchors = 3  # Generate anchors for h1, h2, and h3
+
+# Configure myst-parser to handle images
+myst_url_schemes = ("http", "https", "mailto", "ftp")
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,115 +1,24 @@
 ``stac-validator`` documentation
 ################################
 
-``stac-validator`` is a library and cli tool for validating `SpatioTemporal Asset Catalogs (STAC) <https://stacspec.org/>`_. It is written in Python and can be used to validate STAC Items, Collections, and Catalogs.  
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+   :start-after: # SpatioTemporal Asset Catalog Validator
+   :end-before: ## Sponsors and Supporters
 
-``stac-validator`` was first developed by `Sparkgeo <https://sparkgeo.com/>`_. It later received support from the `Radiant Earth Foundation <https://radiant.earth/>`_ as part of the work done for `stac-check <https://github.com/stac-utils/stac-check/>`_, which uses the ``stac-validator`` library and adds linting functionality. The ``stac-validator`` CLI tool offers more validation options compared to stac-check. Recent development on ``stac-validator`` has been supported by `Sparkgeo <https://sparkgeo.com/>`_ as well as other open-source contributors. 
-
-Installation
-------------
-
-``stac-validator`` can be installed from PyPI:        
-
-.. code-block:: bash
-
-   $ pip install stac-validator      
-
-CLI Usage
----------
-
-``stac-validator`` can be used as a library or as a command line tool.
-
-.. code-block:: shell
-
-   $ stac-validator --help
-
-   Usage: stac-validator [OPTIONS] STAC_FILE
-
-   The `stac-validator` command line tool. Validates a STAC
-   file against the STAC specification and prints the validation results to the
-   console.
-
-   Args:
-      stac_file (str): Path to the STAC file to be validated.
-      item_collection (bool): Whether to validate item collection responses.
-      pages (int): Maximum number of pages to validate via `item_collection`.
-      recursive (bool): Whether to recursively validate all related STAC objects.
-      max_depth (int): Maximum depth to traverse when recursing.
-      core (bool): Whether to validate core STAC objects only.
-      extensions (bool): Whether to validate extensions only.
-      links (bool): Whether to additionally validate links. Only works with default mode.
-      assets (bool): Whether to additionally validate assets. Only works with default mode.
-      custom (str): Path to a custom schema file to validate against.
-      verbose (bool): Whether to enable verbose output for recursive mode.
-      no_output (bool): Whether to print output to console.
-      log_file (str): Path to a log file to save full recursive output.
-
-   Returns:     
-      None
-
-   Raises:     
-      SystemExit: Exits the program with a status code of 0 if the STAC file is valid, or 1 if it is invalid.
-
-   Options:
-      --core                   Validate core stac object only without extensions.
-      --extensions             Validate extensions only.
-      --links                  Additionally validate links. Only works with default mode.
-      --assets                 Additionally validate assets. Only works with default mode.
-      -c, --custom TEXT        Validate against a custom schema (local filepath or remote schema).
-      -r, --recursive          Recursively validate all related stac objects.
-      -m, --max-depth INTEGER  Maximum depth to traverse when recursing. Omit this argument to get full recursion. 
-                               Ignored if `recursive == False`.
-      --item-collection        Validate item collection response. Can be combined with --pages. Defaults to one page.
-      -p, --pages INTEGER      Maximum number of pages to validate via --item-collection. Defaults to one page.
-      -v, --verbose            Enables verbose output for recursive mode.
-      --no_output              Do not print output to console.
-      --log_file TEXT          Save full recursive output to log file (local filepath).
-      --version                Show the version and exit.
-      --help                   Show this message and exit.
-
-``stac-validator`` can be used to validate local or remotely-hosted STAC objects. The tool will return a list of validation errors if the STAC object is invalid.  
-
-Library
-~~~~~~~
-
-``stac-validator`` can be used as a library to validate STAC Items, Collections, and Catalogs. 
-It can be used with local or remotely-hosted STAC objects as well as STAC objects represented as a Python dictionary. 
-The library will return a list of validation errors if the STAC object is invalid.
-
-Examples
-~~~~~~~~
-
-``python dictionary``
-
-.. code-block:: bash
-
-   from stac_validator import stac_validator
-
-   stac = stac_validator.StacValidate()
-   stac.validate_dict(dictionary)
-   print(stac.message)
-
-``python item-collection``
-
-.. code-block:: bash
-
-   from stac_validator import stac_validator
-
-   stac = stac_validator.StacValidate()
-   stac.validate_item_collection_dict(item_collection_dict)
-   print(stac.message)
-
-
-Versions supported
-~~~~~~~~~~~~~~~~~~
-
-``stac-validator`` supports the following versions of the STAC specification:
-
-``[0.8.0, 0.8.1, 0.9.0, 1.0.0-beta.1, 1.0.0-beta.2, 1.0.0-rc.1, 1.0.0-rc.2, 1.0.0-rc.3, 1.0.0-rc.4, 1.0.0]``
+For more detailed documentation, please see the following pages:
 
 .. toctree::
-   :maxdepth: 1
-
+   :maxdepth: 2
+   :caption: Contents:
+
    cli
-   utilities
    validator
+   utilities
+
+Indices and tables
+=================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,4 @@
+sphinx>=4.0.0
+sphinx_rtd_theme>=1.0.0
+myst-parser>=0.15.0
+sphinx-autodoc-typehints>=1.12.0
diff --git a/pdoc/stac_validator/index.html b/pdoc/stac_validator/index.html