From 93107e6bfe7a55bfe6e320920a599f11e6739cf4 Mon Sep 17 00:00:00 2001 From: Edmond Chuc <37032744+edmondchuc@users.noreply.github.com> Date: Thu, 28 Jul 2022 02:13:10 +1000 Subject: [PATCH] Add development container and update READMEs. Add Sphinx furo theme. (#221) --- .devcontainer/Dockerfile | 25 ++++++++++++ .devcontainer/devcontainer.json | 69 +++++++++++++++++++++++++++++++++ .github/workflows/artifacts.yml | 2 +- .github/workflows/release.yml | 2 +- .github/workflows/tests.yml | 2 +- .gitignore | 6 ++- README.md | 50 +++++++++++++----------- python/README.md | 30 +++++++++----- python/docs/conf.py | 2 +- 9 files changed, 151 insertions(+), 37 deletions(-) create mode 100644 .devcontainer/Dockerfile create mode 100644 .devcontainer/devcontainer.json diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 00000000..4f73f4b2 --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,25 @@ +# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.241.1/containers/rust/.devcontainer/base.Dockerfile + +# [Choice] Debian OS version (use bullseye on local arm64/Apple Silicon): buster, bullseye +ARG VARIANT="bullseye" +FROM mcr.microsoft.com/vscode/devcontainers/rust:0-${VARIANT} + +# [Optional] Uncomment this section to install additional packages. +RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \ + && apt-get -y install --no-install-recommends \ + python3 \ + python3-venv \ + python-is-python3 \ + libclang-dev + +ENV VIRTUAL_ENV=/opt/venv +RUN python -m venv $VIRTUAL_ENV +ENV PATH="$VIRTUAL_ENV/bin:$PATH" +RUN pip install --no-cache-dir \ + maturin \ + sphinx \ + sphinx-autobuild \ + furo + +# Change owner to the devcontainer user +RUN chown -R 1000:1000 $VIRTUAL_ENV diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 00000000..e8978483 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,69 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at: +// https://github.com/microsoft/vscode-dev-containers/tree/v0.241.1/containers/rust +{ + "name": "Rust", + "build": { + "dockerfile": "Dockerfile", + "args": { + // Use the VARIANT arg to pick a Debian OS version: buster, bullseye + // Use bullseye when on local on arm64/Apple Silicon. + "VARIANT": "bullseye" + } + }, + "runArgs": ["--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined"], + + // Configure tool-specific properties. + "customizations": { + // Configure properties specific to VS Code. + "vscode": { + // Set *default* container specific settings.json values on container create. + "settings": { + "lldb.executable": "/usr/bin/lldb", + // VS Code don't watch files under ./target + "files.watcherExclude": { + "**/target/**": true + }, + "rust-analyzer.checkOnSave.command": "clippy", + + "python.defaultInterpreterPath": "/opt/venv/bin/python", + "python.linting.enabled": true, + "python.linting.pylintEnabled": true, + "python.formatting.autopep8Path": "/usr/local/py-utils/bin/autopep8", + "python.formatting.blackPath": "/usr/local/py-utils/bin/black", + "python.formatting.yapfPath": "/usr/local/py-utils/bin/yapf", + "python.linting.banditPath": "/usr/local/py-utils/bin/bandit", + "python.linting.flake8Path": "/usr/local/py-utils/bin/flake8", + "python.linting.mypyPath": "/usr/local/py-utils/bin/mypy", + "python.linting.pycodestylePath": "/usr/local/py-utils/bin/pycodestyle", + "python.linting.pydocstylePath": "/usr/local/py-utils/bin/pydocstyle", + "python.linting.pylintPath": "/opt/venv/bin/pylint", + "python.testing.pytestPath": "/opt/venv/bin/pytest" + }, + + // Add the IDs of extensions you want installed when the container is created. + "extensions": [ + "vadimcn.vscode-lldb", + "mutantdino.resourcemonitor", + "rust-lang.rust-analyzer", + "tamasfe.even-better-toml", + "serayuzgur.crates", + "ms-python.python", + "ms-python.vscode-pylance", + "esbenp.prettier-vscode", + "stardog-union.stardog-rdf-grammars" + ] + } + }, + + // Use 'forwardPorts' to make a list of ports inside the container available locally. + // "forwardPorts": [], + + // Use 'postCreateCommand' to run commands after the container is created. + "postCreateCommand": "git submodule update --init && cargo build", + + // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root. + "remoteUser": "vscode", + "features": { + "python": "3.10" + } +} diff --git a/.github/workflows/artifacts.yml b/.github/workflows/artifacts.yml index 2abebb70..1d1952c8 100644 --- a/.github/workflows/artifacts.yml +++ b/.github/workflows/artifacts.yml @@ -17,7 +17,7 @@ jobs: with: python-version: 3.8 - run: python -m venv python/venv - - run: source python/venv/bin/activate && pip install --upgrade maturin sphinx + - run: source python/venv/bin/activate && pip install --upgrade maturin sphinx furo - run: source venv/bin/activate && maturin develop working-directory: ./python - run: source ../venv/bin/activate && sphinx-build -M doctest . build diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4939eba4..d0a7a3a7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -184,7 +184,7 @@ jobs: with: python-version: 3.8 - run: python -m venv python/venv - - run: source python/venv/bin/activate && pip install --upgrade maturin sphinx + - run: source python/venv/bin/activate && pip install --upgrade maturin sphinx furo - run: source venv/bin/activate && maturin develop working-directory: ./python - run: source ../venv/bin/activate && sphinx-build -M doctest . build diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index b64a3fa6..657b5b61 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -89,7 +89,7 @@ jobs: - uses: actions/setup-python@v2 with: python-version: "3.10" - - run: pip install --upgrade maturin sphinx + - run: pip install --upgrade maturin sphinx furo - run: maturin sdist -m python/Cargo.toml - run: pip install target/wheels/*.tar.gz - run: python -m unittest diff --git a/.gitignore b/.gitignore index a3d66de0..1e7d34b7 100644 --- a/.gitignore +++ b/.gitignore @@ -8,4 +8,8 @@ lib/tests/rocksdb_bc_data venv .env data/ -.htpasswd \ No newline at end of file +.htpasswd +**/docs/_build +**/docs/build +*.so +*.pyc \ No newline at end of file diff --git a/README.md b/README.md index 671a229c..3784bf62 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ -Oxigraph -======== +# Oxigraph -[![Latest Version](https://img.shields.io/crates/v/oxigraph.svg)](https://crates.io/crates/oxigraph) +[![Latest Version](https://img.shields.io/crates/v/oxigraph.svg)](https://crates.io/crates/oxigraph) [![Released API docs](https://docs.rs/oxigraph/badge.svg)](https://docs.rs/oxigraph) [![PyPI](https://img.shields.io/pypi/v/pyoxigraph)](https://pypi.org/project/pyoxigraph/) [![npm](https://img.shields.io/npm/v/oxigraph)](https://www.npmjs.com/package/oxigraph) @@ -21,23 +20,32 @@ The development roadmap is using [GitHub milestones](https://github.com/oxigraph Oxigraph internal design [is described on the wiki](https://github.com/oxigraph/oxigraph/wiki/Architecture). It is split into multiple parts: -* [The database written as a Rust library](https://crates.io/crates/oxigraph). Its source code is in the `lib` directory. -[![Latest Version](https://img.shields.io/crates/v/oxigraph.svg)](https://crates.io/crates/oxigraph) -[![Released API docs](https://docs.rs/oxigraph/badge.svg)](https://docs.rs/oxigraph) -* [`pyoxigraph` that exposes Oxigraph to the Python world](https://oxigraph.org/pyoxigraph/). Its source code is in the `python` directory. [![PyPI](https://img.shields.io/pypi/v/pyoxigraph)](https://pypi.org/project/pyoxigraph/) -* [JavaScript bindings for Oxigraph](https://www.npmjs.com/package/oxigraph). WebAssembly is used to package Oxigraph into a NodeJS compatible NPM package. Its source code is in the `js` directory. -[![npm](https://img.shields.io/npm/v/oxigraph)](https://www.npmjs.com/package/oxigraph) -* [Oxigraph server](https://crates.io/crates/oxigraph_server) that provides a standalone binary of a web server implementing the [SPARQL 1.1 Protocol](https://www.w3.org/TR/sparql11-protocol/) and the [SPARQL 1.1 Graph Store Protocol](https://www.w3.org/TR/sparql11-http-rdf-update/). Its source code is in the `server` directory. -[![Latest Version](https://img.shields.io/crates/v/oxigraph_server.svg)](https://crates.io/crates/oxigraph_server) -[![Docker Image Version (latest semver)](https://img.shields.io/docker/v/oxigraph/oxigraph?sort=semver)](https://hub.docker.com/r/oxigraph/oxigraph) + +- [The database written as a Rust library](https://crates.io/crates/oxigraph). Its source code is in the `lib` directory. + [![Latest Version](https://img.shields.io/crates/v/oxigraph.svg)](https://crates.io/crates/oxigraph) + [![Released API docs](https://docs.rs/oxigraph/badge.svg)](https://docs.rs/oxigraph) +- [`pyoxigraph` that exposes Oxigraph to the Python world](https://oxigraph.org/pyoxigraph/). Its source code is in the `python` directory. [![PyPI](https://img.shields.io/pypi/v/pyoxigraph)](https://pypi.org/project/pyoxigraph/) +- [JavaScript bindings for Oxigraph](https://www.npmjs.com/package/oxigraph). WebAssembly is used to package Oxigraph into a NodeJS compatible NPM package. Its source code is in the `js` directory. + [![npm](https://img.shields.io/npm/v/oxigraph)](https://www.npmjs.com/package/oxigraph) +- [Oxigraph server](https://crates.io/crates/oxigraph_server) that provides a standalone binary of a web server implementing the [SPARQL 1.1 Protocol](https://www.w3.org/TR/sparql11-protocol/) and the [SPARQL 1.1 Graph Store Protocol](https://www.w3.org/TR/sparql11-http-rdf-update/). Its source code is in the `server` directory. + [![Latest Version](https://img.shields.io/crates/v/oxigraph_server.svg)](https://crates.io/crates/oxigraph_server) + [![Docker Image Version (latest semver)](https://img.shields.io/docker/v/oxigraph/oxigraph?sort=semver)](https://hub.docker.com/r/oxigraph/oxigraph) Oxigraph implements the following specifications: -* [SPARQL 1.1 Query](https://www.w3.org/TR/sparql11-query/), [SPARQL 1.1 Update](https://www.w3.org/TR/sparql11-update/), and [SPARQL 1.1 Federated Query](https://www.w3.org/TR/sparql11-federated-query/). -* [Turtle](https://www.w3.org/TR/turtle/), [TriG](https://www.w3.org/TR/trig/), [N-Triples](https://www.w3.org/TR/n-triples/), [N-Quads](https://www.w3.org/TR/n-quads/), and [RDF XML](https://www.w3.org/TR/rdf-syntax-grammar/) RDF serialization formats for both data ingestion and retrieval using the [Rio library](https://github.com/oxigraph/rio). -* [SPARQL Query Results XML Format](http://www.w3.org/TR/rdf-sparql-XMLres/), [SPARQL 1.1 Query Results JSON Format](https://www.w3.org/TR/sparql11-results-json/) and [SPARQL 1.1 Query Results CSV and TSV Formats](https://www.w3.org/TR/sparql11-results-csv-tsv/). + +- [SPARQL 1.1 Query](https://www.w3.org/TR/sparql11-query/), [SPARQL 1.1 Update](https://www.w3.org/TR/sparql11-update/), and [SPARQL 1.1 Federated Query](https://www.w3.org/TR/sparql11-federated-query/). +- [Turtle](https://www.w3.org/TR/turtle/), [TriG](https://www.w3.org/TR/trig/), [N-Triples](https://www.w3.org/TR/n-triples/), [N-Quads](https://www.w3.org/TR/n-quads/), and [RDF XML](https://www.w3.org/TR/rdf-syntax-grammar/) RDF serialization formats for both data ingestion and retrieval using the [Rio library](https://github.com/oxigraph/rio). +- [SPARQL Query Results XML Format](http://www.w3.org/TR/rdf-sparql-XMLres/), [SPARQL 1.1 Query Results JSON Format](https://www.w3.org/TR/sparql11-results-json/) and [SPARQL 1.1 Query Results CSV and TSV Formats](https://www.w3.org/TR/sparql11-results-csv-tsv/). A preliminary benchmark [is provided](bench/README.md). There is also [a document describing Oxigraph technical architecture](https://github.com/oxigraph/oxigraph/wiki/Architecture). +## Development + +The easiest way to set up the development environment is to use Visual Studio Code's [development containers](https://code.visualstudio.com/docs/remote/containers). Note that this requires Docker Desktop on Windows and Mac and Docker CE/EE on Linux. + +Open the repository with Visual Studio Code and use the Command Palette to run `Remote-Containers: Rebuild Container`. This will re-open the project inside a development container with the Rust toolchain and Python dependencies installed. For more details on how the development container is set up, see [.devcontainer/devcontainer.json](.devcontainer/devcontainer.json) and [.devcontainer/Dockerfile](.devcontainer/Dockerfile). + +For further development details, see the README in each of the respective sub-projects. ## Help @@ -46,18 +54,16 @@ Feel free to use [GitHub discussions](https://github.com/oxigraph/oxigraph/discu If you need advanced support or are willing to pay to get some extra features, feel free to reach out to [Tpt](https://github.com/Tpt/). - ## License This project is licensed under either of - * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or - http://www.apache.org/licenses/LICENSE-2.0) - * MIT license ([LICENSE-MIT](LICENSE-MIT) or - http://opensource.org/licenses/MIT) - -at your option. +- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or + http://www.apache.org/licenses/LICENSE-2.0) +- MIT license ([LICENSE-MIT](LICENSE-MIT) or + http://opensource.org/licenses/MIT) +at your option. ### Contribution diff --git a/python/README.md b/python/README.md index 3465f196..2dae0fea 100644 --- a/python/README.md +++ b/python/README.md @@ -1,5 +1,4 @@ -Pyoxigraph (Oxigraph for Python) -================================ +# Pyoxigraph (Oxigraph for Python) [![PyPI](https://img.shields.io/pypi/v/pyoxigraph)](https://pypi.org/project/pyoxigraph/) ![PyPI - Implementation](https://img.shields.io/pypi/implementation/pyoxigraph) @@ -9,13 +8,13 @@ Pyoxigraph (Oxigraph for Python) Pyoxigraph is a graph database library implementing the [SPARQL](https://www.w3.org/TR/sparql11-overview/) standard. It is a Python library written on top of [Oxigraph](https://crates.io/crates/oxigraph). - + Pyoxigraph offers two stores with [SPARQL 1.1](https://www.w3.org/TR/sparql11-overview/) capabilities. One of the store is in-memory, and the other one is disk based. It also provides a set of utility functions for reading, writing and processing RDF files in -[Turtle](https://www.w3.org/TR/turtle/), -[TriG](https://www.w3.org/TR/trig/), +[Turtle](https://www.w3.org/TR/turtle/), +[TriG](https://www.w3.org/TR/trig/), [N-Triples](https://www.w3.org/TR/n-triples/), [N-Quads](https://www.w3.org/TR/n-quads/) and [RDF/XML](https://www.w3.org/TR/rdf-syntax-grammar/). @@ -32,7 +31,6 @@ Pyoxigraph documentation is [available on the Oxigraph website](https://oxigraph To build and install the development version of pyoxigraph you need to clone this git repository and to run `pip install .` in the `python` directory (the one this README is in). - ## Help Feel free to use [GitHub discussions](https://github.com/oxigraph/oxigraph/discussions) or [the Gitter chat](https://gitter.im/oxigraph/community) to ask questions or talk about Oxigraph. @@ -40,7 +38,6 @@ Feel free to use [GitHub discussions](https://github.com/oxigraph/oxigraph/discu If you need advanced support or are willing to pay to get some extra features, feel free to reach out to [Tpt](https://github.com/Tpt). - ## How to contribute Pyoxigraph is written in Rust using [PyO3](https://github.com/PyO3/pyo3). @@ -49,21 +46,34 @@ Pyoxigraph is built using [Maturin](https://github.com/PyO3/maturin). Maturin could be installed using the `pip install 'maturin>=0.9,<0.10'`. To install a development version of Oxigraph just run `maturin develop` in this README directory. +### Tests + The Python bindings tests are written in Python. To run them use `python -m unittest` in the `tests` directory. +### Docs + +The Sphinx documentation can be generated and viewed in the browser using the following command: + +``` +sphinx-autobuild docs docs/_build/html +``` + +Note that you will need to have [sphinx-autobuild](https://pypi.org/project/sphinx-autobuild/) installed. This should be installed already if you are using this repository's development container. + +Alternatively, you can use `sphinx-build` with Python's `http.server` to achieve the same thing. + ## License This project is licensed under either of -* Apache License, Version 2.0, ([LICENSE-APACHE](../LICENSE-APACHE) or +- Apache License, Version 2.0, ([LICENSE-APACHE](../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) -* MIT license ([LICENSE-MIT](../LICENSE-MIT) or +- MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT) at your option. - ### Contribution Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Oxigraph by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. diff --git a/python/docs/conf.py b/python/docs/conf.py index 73d9bcef..49da1c4b 100644 --- a/python/docs/conf.py +++ b/python/docs/conf.py @@ -22,7 +22,7 @@ exclude_patterns = ["build", "Thumbs.db", ".DS_Store"] # -- Options for HTML output ------------------------------------------------- -html_theme = "classic" +html_theme = "furo" html_static_path = [] html_logo = "../../logo.svg" html_favicon = "../../logo.svg"