Skip to content

Commit b2b82cb

Browse files
raederanraederan
committed
docs: restructure docs with hero landing page and tabbed guides
Rebuild the site after the oold-python layout: hero landing page with logo and call-to-action buttons, about and get-started pages (tabbed uv/pip install, extras table, quickstart from real examples), API reference grouped under docs/api (fixing a sphinx-era gitignore rule that hid it), and dev.md as a tabbed make/manual mirror of the simplified CONTRIBUTING. Slim README down to pitch, install, quickstart and links
1 parent 1c4c97e commit b2b82cb

20 files changed

Lines changed: 434 additions & 222 deletions

‎.gitignore‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,6 @@ coverage.xml
4242
build/*
4343
dist/*
4444
sdist/*
45-
docs/api/*
46-
docs/_rst/*
47-
docs/_build/*
4845
cover/*
4946
MANIFEST
5047
site

‎CONTRIBUTING.md‎

Lines changed: 17 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,39 @@
11
# Contributing
22

3-
Contributions are welcome! You can help by reporting bugs, implementing
4-
features, or improving documentation. File issues and PRs at
3+
Contributions are welcome! File issues and pull requests at
54
[github.com/OpenSemanticLab/osw-python](https://github.com/OpenSemanticLab/osw-python).
65

7-
## Development Setup
6+
## Workflow
87

9-
Requires `uv` and `git`.
8+
Requires [uv](https://docs.astral.sh/uv/) and `git`.
109

1110
```bash
1211
git clone git@github.com:YOUR_NAME/osw-python.git
1312
cd osw-python
13+
make install # environment + pre-commit hooks
1414
```
1515

16-
With `make`:
17-
18-
```bash
19-
make install
20-
```
21-
22-
Without `make`:
23-
24-
```bash
25-
uv sync
26-
uv run pre-commit install
27-
```
28-
29-
## Making Changes
30-
3116
1. Create a branch: `git checkout -b name-of-your-fix`
3217
2. Make your changes and add tests in `tests/`
33-
3. Run checks and tests (see below)
34-
4. Commit and push, then open a pull request
35-
36-
### Checks and tests
37-
38-
With `make`:
39-
40-
```bash
41-
make check # lint, type-check, dependency audit
42-
make test # pytest with coverage
43-
```
44-
45-
Without `make`:
46-
47-
```bash
48-
uv lock --locked
49-
uv run pre-commit run -a
50-
uv run ty check
51-
uv run deptry src
52-
uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=xml
53-
```
54-
55-
Integration tests need credentials for a test wiki and are excluded by
56-
default:
57-
58-
```bash
59-
uv run pytest tests/integration -o addopts="" --wiki_domain "<domain>" --wiki_username "<login>" --wiki_password "<password>"
60-
```
18+
3. Run `make check` (lint, type-check, dependency audit) and `make test`
19+
4. Commit, push and open a pull request
6120

62-
### Docs
21+
`make help` lists all targets; the
22+
[development guide](https://opensemanticlab.github.io/osw-python/dev/)
23+
covers details such as running the integration tests and serving the docs
24+
locally.
6325

64-
With `make`:
65-
66-
```bash
67-
make docs # serve with live reload at http://localhost:8000
68-
make docs-test # strict build, fails on any warning
69-
```
26+
## Releasing
7027

71-
Without `make`:
28+
Maintainers release by pushing a version tag; CI does the rest (build,
29+
publish to PyPI via trusted publishing, deploy versioned docs):
7230

7331
```bash
74-
uv run zensical serve
75-
uv run zensical build -s
32+
git tag v1.2.0 && git push origin v1.2.0
7633
```
7734

78-
## Releasing
79-
80-
Releases are published automatically by CI when a version tag is pushed.
81-
82-
1. Ensure all changes are merged to `main`
83-
2. Tag the commit and push:
84-
85-
```bash
86-
git tag v1.2.0
87-
git push origin v1.2.0
88-
```
89-
90-
CI will build the package (`uv build`), publish it to PyPI via trusted
91-
publishing, and deploy the versioned docs to GitHub Pages. The version is
92-
derived from the git tag via `hatch-vcs`, so no manual version bumping is
93-
needed.
94-
9535
## AI Guidelines
9636

97-
We believe that AI, and in particular LLMs, can be helpful conventional
98-
tools to accelerate development and improve quality when used responsibly.
99-
AI or any other tool is never the author of code; a human developer always
100-
is. Therefore, it is mandatory to carefully review all generated content
101-
for correctness, quality, and the absence of legal and ethical issues. For
102-
consistency, please avoid patterns that are hard to maintain manually, such
103-
as duplicated content or special characters like em dashes or UTF icons.
37+
AI tools may be used to assist development, but a human developer is always
38+
the author: carefully review all generated content for correctness, quality
39+
and license compliance before submitting it.

‎README.md‎

Lines changed: 30 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -6,79 +6,50 @@
66

77
# osw
88

9-
Python toolset for data processing, queries, wikicode generation and page manipulation within OpenSemanticLab.
9+
Python toolset for data processing, queries, wikicode generation and page
10+
manipulation within [OpenSemanticLab](https://github.com/OpenSemanticLab).
1011

11-
General features for object-oriented interaction with knowledge graphs are planned to be moved to a standalone package:
12-
[oold-python](https://github.com/OO-LD/oold-python)
12+
Work with OpenSemanticLab instances the way you work with Python objects:
13+
load pages as typed pydantic entities, query with semantic search, generate
14+
models from the schemas stored in the wiki, and write changes back.
1315

14-
## Installation
15-
```
16-
pip install osw
17-
```
16+
**Documentation: <https://opensemanticlab.github.io/osw-python/>**
1817

19-
### Variants
20-
| Variant | Description |
21-
| -- | -- |
22-
`osw[wikitext]` | Additional functions in `wiki_tools` to transform mediawiki markup / templates
23-
`osw[DB]` | interact with SQL databases per DatabaseController
24-
`osw[S3]` | Interact with S3 Stores per S3FileController
25-
`osw[dataimport]` | Additional tools to import data
26-
`osw[UI]` | To use a helper UI to work with entity slots
27-
28-
To install multiple optional/extra dependencies run
29-
```
30-
pip install osw[opt1, opt2, ...]
31-
```
32-
33-
To install all optional/extra dependencies run
34-
```
35-
pip install osw[all]
36-
```
37-
38-
## Getting started
39-
You can find examples in the tutorial folder, e.g. [entity creation](https://github.com/OpenSemanticLab/osw-python/blob/main/examples/create_entity.py), [entity manipulaton](https://github.com/OpenSemanticLab/osw-python/blob/main/examples/store_entity.py), [querying](https://github.com/OpenSemanticLab/osw-python/blob/main/examples/query_minimal.py), and [file downloads](https://github.com/OpenSemanticLab/osw-python/blob/main/examples/file_download_minimal.py)
40-
41-
## Troubleshooting
18+
## Installation
4219

43-
### `Error: datamodel-codegen not found`
44-
make sure datamodel-codegen is installed and included in PATH, e. g. on jupyterlab:
45-
```
46-
os.environ["PATH"] += os.pathsep + "/home/jovyan/.local/bin"
20+
```bash
21+
pip install osw
4722
```
4823

49-
## Documentation
50-
51-
https://opensemanticlab.github.io/osw-python/
24+
Optional extras (`osw[wikitext]`, `osw[DB]`, `osw[S3]`, `osw[dataimport]`,
25+
`osw[UI]`, `osw[all]`) are described in the
26+
[Get Started guide](https://opensemanticlab.github.io/osw-python/get-started/).
5227

53-
### Tutorials
28+
## Quickstart
5429

55-
Tutorials can be found at [tutorials](docs/tutorials/)
56-
- [Basics](docs/tutorials/basics.ipynb) - a description of the data model of OpenSemanticLab and how to interact with it
30+
```python
31+
from osw.express import OswExpress
5732

58-
## Development
59-
60-
Dev install (requires [uv](https://docs.astral.sh/uv/))
61-
62-
```bash
63-
make install
33+
osw = OswExpress(domain="wiki-dev.open-semantic-lab.org")
34+
instances = osw.site.semantic_search("[[Category:Item]]")
35+
print(instances)
6436
```
6537

66-
Run code quality checks (pre-commit incl. ruff, ty, deptry)
38+
More runnable scripts live in [examples/](examples/), and the
39+
[Basics tutorial](docs/tutorials/basics.ipynb) walks through the
40+
OpenSemanticLab data model.
6741

68-
```bash
69-
make check
70-
```
42+
## Contributing
7143

72-
Run tests (integration tests excluded by default)
44+
Contributions are welcome, see [CONTRIBUTING.md](CONTRIBUTING.md).
45+
Development setup, checks and tests are one command each: `make install`,
46+
`make check`, `make test`.
7347

74-
```bash
75-
make test
76-
```
48+
## Related projects
7749

78-
Run integration tests (tests are skipped if login params are not provided)
50+
General features for object-oriented interaction with knowledge graphs live
51+
in the standalone package [oold-python](https://github.com/OO-LD/oold-python).
7952

80-
```bash
81-
uv run pytest tests/integration -o addopts="" --wiki_domain "<osl-domain>" --wiki_username "<(bot)login>" --wiki_password "<password>" --db_username "<username>" --db_password "<password>"
82-
```
53+
## License
8354

84-
See [docs/dev.md](docs/dev.md) for details.
55+
AGPL-3.0-or-later, see [LICENSE.txt](LICENSE.txt).

‎docs/about.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# About
2+
3+
**osw-python** is the Python toolset for
4+
[OpenSemanticLab](https://github.com/OpenSemanticLab): data processing,
5+
semantic queries, wikicode generation and page manipulation, all against the
6+
knowledge graph of an OpenSemanticLab / OpenSemanticWorld instance.
7+
8+
[![PyPI-Server](https://img.shields.io/pypi/v/osw.svg)](https://pypi.org/project/osw/)
9+
[![DOI](https://zenodo.org/badge/458130867.svg)](https://zenodo.org/badge/latestdoi/458130867)
10+
[![Codecov](https://codecov.io/gh/OpenSemanticLab/osw-python/graph/badge.svg)](https://codecov.io/gh/OpenSemanticLab/osw-python)
11+
[![License](https://img.shields.io/github/license/OpenSemanticLab/osw-python.svg)](https://github.com/OpenSemanticLab/osw-python/blob/main/LICENSE.txt)
12+
13+
## Why osw-python?
14+
15+
- **Typed entities** - pages are loaded as pydantic models generated from
16+
the JSON schemas stored in the wiki itself
17+
- **Semantic queries** - run semantic search and SPARQL queries from Python
18+
- **Full page control** - read and write structured data, wikitext and
19+
files on any page slot
20+
- **Controller pattern** - attach runtime behavior (databases, S3 stores,
21+
file handling) to entities without polluting the data model
22+
- **Express mode** - one-liner site access with credential handling built in
23+
24+
General features for object-oriented interaction with knowledge graphs live
25+
in the standalone package [oold-python](https://github.com/OO-LD/oold-python),
26+
which osw-python builds on.
27+
28+
## Ecosystem
29+
30+
| Project | Role |
31+
| ------- | ---- |
32+
| [OpenSemanticLab](https://github.com/OpenSemanticLab) | The platform osw-python talks to |
33+
| [oold-python](https://github.com/OO-LD/oold-python) | Object-oriented linked data foundation |
34+
| [opensemantic.core](https://github.com/OpenSemanticWorld-Packages/opensemantic.core-python) | Generated core data model |
35+
36+
## License
37+
38+
AGPL-3.0-or-later, see
39+
[LICENSE.txt](https://github.com/OpenSemanticLab/osw-python/blob/main/LICENSE.txt).

‎docs/api/auth.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Authentication
2+
3+
Credential handling for wiki and service logins.
4+
5+
::: osw.auth.CredentialManager

‎docs/api/controller.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Controllers
2+
3+
A controller extends a model class with functions.
4+
5+
## Entity
6+
7+
::: osw.controller.Entity
8+
9+
## DatabaseController
10+
11+
::: osw.controller.DatabaseController

‎docs/api/core.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# OSW
2+
3+
The central class for interacting with an OpenSemanticWorld instance.
4+
5+
::: osw.core.OSW

‎docs/api/index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# API Reference
2+
3+
The most important entry points of the package:
4+
5+
| Page | Contents |
6+
| ---- | -------- |
7+
| [OSW](core.md) | The central `OSW` class: load, store and query entities |
8+
| [Wiki Tools](wiki-tools.md) | Helper functions for pages, queries and wikitext |
9+
| [Authentication](auth.md) | `CredentialManager` for logins and tokens |
10+
| [Controllers](controller.md) | Runtime behavior attached to entities |
11+
| [Model](model.md) | The generated data model |

‎docs/api/model.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Model
2+
3+
The data model is generated from the JSON schemas of the wiki. The core
4+
model is maintained in
5+
[opensemantic.core-python](https://github.com/OpenSemanticWorld-Packages/opensemantic.core-python/blob/main/src/opensemantic/core/v1/_model.py)
6+
and extended dynamically at runtime via `OSW.fetch_schema`.

‎docs/api/wiki-tools.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Wiki Tools
2+
3+
Collection of helper functions for pages, queries and wikitext.
4+
5+
::: osw.wiki_tools

0 commit comments

Comments
 (0)