Skip to content

Commit 7111c1c

Browse files
jonhealy1jonhealy1
authored
Merge pull request #128 from stac-utils/github-pages-docs
- Migrated documentation from Read the Docs to GitHub Pages - Updated documentation build system to use Sphinx with sphinx_rtd_theme - Added support for Markdown content in documentation using myst-parser - Updated README with instructions for building documentation locally - Added GitHub Actions workflow for automatic documentation deployment
2 parents ba73356 + 110b0ea commit 7111c1c

File tree

18 files changed

+179
-4390
lines changed

18 files changed

+179
-4390
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
paths:
7+
- 'docs/**'
8+
- 'stac_check/**/*.py'
9+
- 'README.md'
10+
pull_request:
11+
branches: [ main ]
12+
paths:
13+
- 'docs/**'
14+
- 'stac_check/**/*.py'
15+
- 'README.md'
16+
# Allow manual triggering
17+
workflow_dispatch:
18+
19+
jobs:
20+
build:
21+
runs-on: ubuntu-latest
22+
steps:
23+
- uses: actions/checkout@v3
24+
- name: Set up Python
25+
uses: actions/setup-python@v4
26+
with:
27+
python-version: '3.9'
28+
- name: Install dependencies
29+
run: |
30+
python -m pip install --upgrade pip
31+
pip install -e ".[docs]"
32+
- name: Build documentation
33+
run: |
34+
sphinx-build -b html docs/ docs/_build/html
35+
- name: Upload documentation artifact
36+
uses: actions/upload-artifact@v4
37+
with:
38+
name: documentation
39+
path: docs/_build/html
40+
retention-days: 7
41+
42+
# Only deploy when pushing to main (not on PRs)
43+
deploy:
44+
needs: build
45+
if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch'
46+
runs-on: ubuntu-latest
47+
permissions:
48+
contents: write
49+
steps:
50+
- name: Download built documentation
51+
uses: actions/download-artifact@v4
52+
with:
53+
name: documentation
54+
path: ./docs-build
55+
- name: Deploy to GitHub Pages
56+
uses: peaceiris/actions-gh-pages@v3
57+
with:
58+
github_token: ${{ secrets.GITHUB_TOKEN }}
59+
publish_dir: ./docs-build
60+
force_orphan: true
61+
commit_message: "Update documentation [skip ci]"

‎.readthedocs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Build documentation in the docs/ directory with Sphinx
2+
sphinx:
3+
configuration: docs/conf.py

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,14 @@ The format is (loosely) based on [Keep a Changelog](http://keepachangelog.com/)
66

77
## Unreleased
88

9+
### Changed
10+
11+
- Migrated documentation from Read the Docs to GitHub Pages ([#128](https://github.com/stac-utils/stac-check/pull/128))
12+
- Updated documentation build system to use Sphinx with sphinx_rtd_theme
13+
- Added support for Markdown content in documentation using myst-parser
14+
- Updated README with instructions for building documentation locally
15+
- Added GitHub Actions workflow for automatic documentation deployment
16+
917
## [v1.7.0] - 2025-06-01
1018

1119
### Added

‎Dockerfile‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,17 @@
11
FROM python:3.9-slim
22

33
WORKDIR /app
4+
5+
# Install build tools and dependencies
6+
RUN apt-get update && \
7+
apt-get install -y --no-install-recommends \
8+
make \
9+
build-essential \
10+
&& rm -rf /var/lib/apt/lists/*
11+
412
COPY . .
513

6-
RUN pip install -e .
14+
# Install the package in development mode with dev and docs extras
15+
RUN pip install -e ".[dev,docs]"
716

817
CMD ["stac_check"]

‎Makefile‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,16 @@ run_docker = docker run -it --rm \
99
.PHONY: shell
1010
shell:
1111
$(run_docker) /bin/bash
12+
13+
.PHONY: docs
14+
docs: ## Build documentation locally
15+
pip install -e ".[docs]"
16+
sphinx-build -b html -E docs/ docs/_build/html
17+
@echo "Documentation built in docs/_build/html"
18+
19+
.PHONY: docker-docs
20+
docker-docs: ## Build documentation inside Docker container
21+
docker build -t stac_check .
22+
docker run --rm -v $(PWD)/docs/_build:/app/docs/_build stac_check sphinx-build -b html -E docs/ docs/_build/html
23+
@echo "Documentation built in docs/_build/html"
24+
@echo "Docker documentation build complete."

‎README.md‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<!-- markdownlint-disable MD033 MD041 -->
44

55
<p align="left">
6-
<img src="assets/stac-check.png" width=560>
6+
<img src="https://raw.githubusercontent.com/stac-utils/stac-check/main/assets/stac-check.png" width=560>
77
</p>
88

99
[![Downloads](https://static.pepy.tech/badge/stac-check?color=blue)](https://pepy.tech/project/stac-check)
@@ -45,7 +45,28 @@ The intent of this project is to provide a validation tool that also follows the
4545

4646
## Documentation
4747

48-
[stac-check.readthedocs.io](https://stac-check.readthedocs.io/en/latest/)
48+
The documentation is hosted on GitHub Pages at [stac-utils.github.io/stac-check](https://stac-utils.github.io/stac-check/).
49+
50+
### Building Documentation Locally
51+
52+
To build the documentation locally:
53+
54+
```bash
55+
# Install the package with documentation dependencies
56+
pip install -e ".[docs]"
57+
58+
# Build the documentation
59+
make docs
60+
```
61+
62+
The built documentation will be available in the `docs/_build/html` directory.
63+
64+
Alternatively, you can build the documentation using Docker:
65+
66+
```bash
67+
# Build the Docker image and documentation
68+
make docker-docs
69+
```
4970

5071
## Installation
5172

‎docs/_static/radiant-earth.webp‎

6.32 KB
Loading

‎docs/_static/stac-check.png‎

4.62 MB
Loading

‎docs/conf.py‎

Lines changed: 37 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
from typing import List
2-
31
# Configuration file for the Sphinx documentation builder.
42
#
53
# For the full list of built-in configuration values, see the documentation:
@@ -8,25 +6,58 @@
86
# -- Project information -----------------------------------------------------
97
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
108

9+
# -- Options for including images from README ----------------------------------
10+
import os
11+
import shutil
12+
1113
project = "stac-check"
14+
copyright = "2025, Jonathan Healy"
1215
author = "Jonathan Healy"
13-
release = "1.5.0"
14-
16+
release = "1.7.0"
1517

1618
# -- General configuration ---------------------------------------------------
1719
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
1820

19-
extensions: List[str] = []
21+
extensions = [
22+
"sphinx.ext.autodoc",
23+
"sphinx.ext.viewcode",
24+
"sphinx.ext.napoleon",
25+
"sphinx_rtd_theme",
26+
"sphinx.ext.intersphinx",
27+
"myst_parser",
28+
]
2029

2130
templates_path = ["_templates"]
2231
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
2332

2433
# -- Options for HTML output -------------------------------------------------
2534
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
2635

27-
html_theme = "alabaster"
36+
html_theme = "sphinx_rtd_theme"
37+
html_static_path = []
38+
39+
# Create _static directory if it doesn't exist
40+
static_dir = os.path.join(os.path.dirname(__file__), "_static")
41+
if not os.path.exists(static_dir):
42+
os.makedirs(static_dir)
43+
44+
# Copy assets from project root to _static directory
45+
assets_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "assets")
46+
if os.path.exists(assets_dir):
47+
for file in os.listdir(assets_dir):
48+
src = os.path.join(assets_dir, file)
49+
dst = os.path.join(static_dir, file)
50+
if os.path.isfile(src):
51+
shutil.copy2(src, dst)
52+
53+
# Now that we've copied files, update static path
2854
html_static_path = ["_static"]
2955

56+
myst_heading_anchors = 3 # Generate anchors for h1, h2, and h3
57+
58+
# Configure myst-parser to handle images
59+
myst_url_schemes = ("http", "https", "mailto", "ftp")
60+
3061
html_css_files = [
3162
"custom.css",
3263
]

‎docs/index.rst‎

Lines changed: 14 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -1,112 +1,23 @@
11
``stac-check`` documentation
22
############################
33

4-
``stac-check`` is a linting and validation tool for STAC assets.
4+
.. include:: ../README.md
5+
:parser: myst_parser.sphinx_
6+
:start-after: # stac-check
7+
:end-before: ## License
58

6-
``stac-check`` is both a CLI tool and Python library. It adds additional linting and validation to the `stac-validator <https://github.com/stac-utils/stac-validator>`_ project.
7-
8-
The intent of this project is to provide a linting tool that also follows the official `STAC Best Practices document <https://github.com/radiantearth/stac-spec/blob/master/best-practices.md>`_.
9-
10-
This project was originally built with funding from the `Radiant Earth Foundation <https://radiant.earth/>`_ and further support has been provided by `Sparkgeo <https://sparkgeo.com/>`_ as well as other contributors.
11-
12-
Installation
13-
------------
14-
15-
``stac-check`` can be installed from `pypi <https://pypi.org/project/stac-check/>`_:
16-
17-
.. code-block:: bash
18-
19-
$ pip install stac-check
20-
21-
to install for local development:
22-
23-
.. code-block:: bash
24-
25-
$ pip install -e .
26-
27-
28-
CLI Usage
29-
---------
30-
31-
``stac-check`` can be used as a Python library or a command line tool.
32-
33-
.. code-block:: shell
34-
35-
$ stac-check --help
36-
37-
Usage: stac-check [OPTIONS] FILE
38-
39-
Options:
40-
--version Show the version and exit.
41-
-l, --links Validate links for format and response.
42-
-a, --assets Validate assets for format and response.
43-
-m, --max-depth INTEGER Maximum depth to traverse when recursing. Omit this
44-
argument to get full recursion. Ignored if
45-
`recursive == False`.
46-
-r, --recursive Recursively validate all related stac objects.
47-
--no-assets-urls Disables the opening of href links when validating assets
48-
(enabled by default).
49-
--header KEY VALUE HTTP header to include in the requests. Can be used
50-
multiple times.
51-
--help Show this message and exit. Show this message and exit.
52-
53-
Examples
54-
~~~~~~~~
55-
56-
.. code-block:: shell
57-
58-
$ stac-check sample_files/0.9.0/landsat8-sample.json
59-
60-
61-
Python Library Usage
62-
--------------------
63-
64-
``stac-check`` can be used as a library to validate and lint STAC Items, Collections, and Catalogs.
65-
It can be used with local or remotely-hosted STAC objects as well as STAC objects represented as a Python dictionary.
66-
67-
Example - lint dictionary
68-
~~~~~~~~~~~~~~~~~~~~~~~~~
69-
70-
.. code-block:: shell
71-
72-
from stac_check.lint import Linter
73-
74-
dict = {
75-
"stac_version": "1.0.0",
76-
"stac_extensions": [],
77-
"type": "Feature",
78-
"id": "20201211_223832_CS2",
79-
"bbox": [
80-
172.91173669923782,
81-
1.3438851951615003,
82-
172.95469614953714,
83-
1.3690476620161975
84-
],
85-
"geometry": {
86-
...
87-
}
88-
linter = Linter(file, assets=True)
89-
90-
for k,v in linter.create_best_practices_dict().items():
91-
print(k,":",v)
92-
93-
STAC Versions supported
94-
~~~~~~~~~~~~~~~~~~~~~~~
95-
96-
``stac-check`` supports the following STAC versions:
97-
98-
``[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, 1.1.0]``
9+
For more detailed documentation, please see the following pages:
9910

10011
.. toctree::
101-
:maxdepth: 1
102-
103-
api
104-
cli
105-
12+
:maxdepth: 2
13+
:caption: Contents:
10614

15+
cli
16+
api
10717

108-
.. Indices and tables
109-
.. ==================
18+
Indices and tables
19+
=================
11020

111-
.. * :ref:`genindex`
112-
.. * :ref:`modindex`
21+
* :ref:`genindex`
22+
* :ref:`modindex`
23+
* :ref:`search`

0 commit comments

Comments
 (0)