Skip to content

Commit b920d33

Browse files
maxrjonesmaxrjones
authored
Add docs site (#7)
1 parent 7380ee5 commit b920d33

10 files changed

Lines changed: 310 additions & 20 deletions

File tree

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,3 +83,5 @@ junit.xml
8383
.DS_Store
8484
tests/.hypothesis
8585
.hypothesis/
86+
87+
site/*

‎.readthedocs.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
version: 2
2+
3+
build:
4+
os: ubuntu-22.04
5+
tools:
6+
python: "3.12"
7+
commands:
8+
- pip install uv
9+
- uv sync --group docs
10+
- uv run mkdocs build
11+
- mkdir -p $READTHEDOCS_OUTPUT/html && cp -r site/* $READTHEDOCS_OUTPUT/html/

‎docs/api.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# API
2+
3+
::: obspec_utils
4+
5+
## Typing
6+
7+
::: obspec_utils.typing.Url
8+
::: obspec_utils.typing.Path
9+
10+
## Registry Utilities
11+
12+
::: obspec_utils.registry.UrlKey

‎docs/index.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Obspec Utils
2+
3+
Utilities for interacting with object storage, based on [obspec](https://github.com/developmentseed/obspec).
4+
5+
## Background
6+
7+
`obspec-utils` provides helpful utilities for working with object storage in Python, built on top of obspec and obstore. The library includes:
8+
9+
1. **ObjectStoreRegistry**: A registry for managing multiple object stores, allowing you to resolve URLs to the appropriate store and path. This is particularly useful when working with datasets that span multiple storage backends or buckets.
10+
11+
2. **File Handlers**: Wrappers around obstore's file reading capabilities that provide a familiar file-like interface, making it easy to integrate with libraries that expect standard Python file objects.
12+
13+
## Getting started
14+
15+
The library can be installed from PyPI:
16+
17+
```bash
18+
python -m pip install obspec-utils
19+
```
20+
21+
## Usage
22+
23+
### ObjectStoreRegistry
24+
25+
The `ObjectStoreRegistry` allows you to register object stores and resolve URLs to the appropriate store:
26+
27+
```python
28+
from obstore.store import S3Store
29+
from obspec_utils import ObjectStoreRegistry
30+
31+
# Create and register stores
32+
s3store = S3Store(bucket="my-bucket", prefix="my-data/")
33+
registry = ObjectStoreRegistry({"s3://my-bucket": s3store})
34+
35+
# Resolve a URL to get the store and path
36+
store, path = registry.resolve("s3://my-bucket/my-data/file.nc")
37+
# path == "file.nc"
38+
```
39+
40+
### File Handlers
41+
42+
The file handlers provide file-like interfaces for reading from object stores:
43+
44+
```python
45+
from obstore.store import S3Store
46+
from obspec_utils import ObstoreReader, ObstoreMemCacheReader
47+
48+
store = S3Store(bucket="my-bucket")
49+
50+
# Standard reader with buffered reads
51+
reader = ObstoreReader(store, "path/to/file.bin", buffer_size=1024*1024)
52+
data = reader.read(100) # Read 100 bytes
53+
54+
# Memory-cached reader for repeated access
55+
cached_reader = ObstoreMemCacheReader(store, "path/to/file.bin")
56+
data = cached_reader.readall() # Read entire file from memory cache
57+
```
58+
59+
## Contributing
60+
61+
1. Clone the repository: `git clone https://github.com/virtual-zarr/obspec-utils.git`
62+
2. Install development dependencies: `uv sync --all-groups`
63+
3. Run the test suite: `uv run --all-groups pytest`
64+
65+
## License
66+
67+
`obspec-utils` is distributed under the terms of the [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) license.

‎docs/overrides/main.html‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{% extends "base.html" %}
2+
3+
{% block outdated %}
4+
You're not viewing the latest version.
5+
<a href="{{ '../' ~ base_url }}">
6+
<strong>Click here to go to latest.</strong>
7+
</a>
8+
{% endblock %}

‎docs/overrides/stylesheets/extra.css‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
:root,
2+
[data-md-color-scheme="default"] {
3+
/* --md-primary-fg-color: #cf3f02;
4+
--md-default-fg-color: #443f3f; */
5+
--boxShadowD: 0px 12px 24px 0px rgba(68, 63, 63, 0.08),
6+
0px 0px 4px 0px rgba(68, 63, 63, 0.08);
7+
}
8+
body {
9+
margin: 0;
10+
padding: 0;
11+
/* font-size: 16px; */
12+
}
13+
h1,
14+
h2,
15+
h3,
16+
h4,
17+
h5,
18+
h6 {
19+
font-family: var(--md-heading-font);
20+
font-weight: bold;
21+
}
22+
.md-typeset h1,
23+
.md-typeset h2 {
24+
font-weight: normal;
25+
color: var(--md-default-fg-color);
26+
}
27+
.md-typeset h3,
28+
.md-typeset h4 {
29+
font-weight: bold;
30+
color: var(--md-default-fg-color);
31+
}
32+
.md-button,
33+
.md-typeset .md-button {
34+
font-family: var(--md-heading-font);
35+
}
36+
.md-content .supheading {
37+
font-family: var(--md-heading-font);
38+
text-transform: uppercase;
39+
color: var(--md-primary-fg-color);
40+
font-size: 0.75rem;
41+
font-weight: bold;
42+
}

‎mkdocs.yml‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Based on https://github.com/developmentseed/obspec/blob/main/mkdocs.yml
2+
site_name: obspec-utils
3+
repo_name: virtual-zarr/obspec-utils
4+
repo_url: https://github.com/virtual-zarr/obspec-utils
5+
site_description: Utilities for interacting with object storage, based on obspec.
6+
site_author: Max Jones
7+
site_url: https://obspec-utils.readthedocs.io
8+
docs_dir: docs
9+
10+
extra:
11+
version:
12+
alias: true
13+
provider: mike
14+
15+
nav:
16+
- "index.md"
17+
- "api.md"
18+
19+
watch:
20+
- src/obspec_utils
21+
- docs
22+
23+
theme:
24+
language: en
25+
name: material
26+
custom_dir: docs/overrides
27+
palette:
28+
# Palette toggle for automatic mode
29+
- media: "(prefers-color-scheme)"
30+
toggle:
31+
icon: material/brightness-auto
32+
name: Switch to light mode
33+
34+
# Palette toggle for light mode
35+
- media: "(prefers-color-scheme: light)"
36+
primary: blue grey
37+
toggle:
38+
icon: material/brightness-7
39+
name: Switch to dark mode
40+
41+
# Palette toggle for dark mode
42+
- media: "(prefers-color-scheme: dark)"
43+
scheme: slate
44+
primary: blue grey
45+
toggle:
46+
icon: material/brightness-4
47+
name: Switch to system preference
48+
49+
font:
50+
text: Roboto
51+
code: Roboto Mono
52+
53+
features:
54+
- content.code.annotate
55+
- content.code.copy
56+
- navigation.indexes
57+
- navigation.instant
58+
- navigation.tracking
59+
- search.suggest
60+
- search.share
61+
62+
extra_css:
63+
- overrides/stylesheets/extra.css
64+
65+
plugins:
66+
- search
67+
- markdown-exec
68+
- mkdocstrings:
69+
enable_inventory: true
70+
handlers:
71+
python:
72+
paths: [src/obspec_utils]
73+
options:
74+
allow_inspection: true
75+
docstring_section_style: list
76+
docstring_style: numpy
77+
line_length: 80
78+
separate_signature: true
79+
show_root_heading: true
80+
show_signature_annotations: true
81+
show_source: false
82+
show_symbol_type_toc: true
83+
signature_crossrefs: true
84+
85+
inventories:
86+
- https://docs.python.org/3/objects.inv
87+
- https://developmentseed.org/obstore/latest/objects.inv
88+
89+
# https://github.com/developmentseed/titiler/blob/50934c929cca2fa8d3c408d239015f8da429c6a8/docs/mkdocs.yml#L115-L140
90+
markdown_extensions:
91+
- admonition
92+
- attr_list
93+
- codehilite:
94+
guess_lang: false
95+
- def_list
96+
- footnotes
97+
- md_in_html
98+
- pymdownx.arithmatex
99+
- pymdownx.betterem
100+
- pymdownx.caret:
101+
insert: false
102+
- pymdownx.details
103+
- pymdownx.escapeall:
104+
hardbreak: true
105+
nbsp: true
106+
- pymdownx.magiclink:
107+
hide_protocol: true
108+
repo_url_shortener: true
109+
- pymdownx.smartsymbols
110+
- pymdownx.snippets
111+
- pymdownx.superfences
112+
- pymdownx.tabbed:
113+
alternate_style: true
114+
- pymdownx.tasklist:
115+
custom_checkbox: true
116+
- pymdownx.tabbed:
117+
alternate_style: true
118+
- pymdownx.tilde
119+
- toc:
120+
permalink: true

‎pyproject.toml‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ dependencies = [
3535
]
3636

3737
[project.urls]
38-
Documentation = "https://github.com/virtual-zarr/obspec-utils#readme"
38+
Documentation = "https://obspec-utils.readthedocs.io"
3939
Issues = "https://github.com/virtual-zarr/obspec-utils/issues"
4040
Source = "https://github.com/virtual-zarr/obspec-utils"
4141

@@ -62,6 +62,14 @@ fsspec = [
6262
dev = [
6363
"ipykernel>=6.29.5",
6464
]
65+
docs = [
66+
"mkdocs-material[imaging]>=9.6.14",
67+
"mkdocs>=1.6.1",
68+
"mkdocstrings>=0.29.1",
69+
"mkdocstrings-python>=1.16.10",
70+
"markdown-exec[ansi]",
71+
"ruff",
72+
]
6573

6674
[tool.hatch.metadata]
6775
allow-direct-references = true

0 commit comments

Comments
 (0)