From 2612f2f4857594c168f19bbdd8974a81f8be1865 Mon Sep 17 00:00:00 2001 From: Anatoly Scherbakov Date: Sat, 30 Mar 2024 21:41:09 +0400 Subject: [PATCH 1/3] Get an mkdocs site going --- .gitignore | 1 + docs/{decisions => blog}/diff-test-results.md | 0 docs/{decisions => blog}/index.md | 0 .../parallelize-test-branches.md | 0 docs/{decisions => blog}/yaml-library.md | 0 jeeves.py | 22 +++ mkdocs.yml | 52 +++++++ poetry.lock | 147 +++++++++++++++++- pyproject.toml | 3 + 9 files changed, 224 insertions(+), 1 deletion(-) rename docs/{decisions => blog}/diff-test-results.md (100%) rename docs/{decisions => blog}/index.md (100%) rename docs/{decisions => blog}/parallelize-test-branches.md (100%) rename docs/{decisions => blog}/yaml-library.md (100%) create mode 100644 mkdocs.yml diff --git a/.gitignore b/.gitignore index 15be44c..519553d 100644 --- a/.gitignore +++ b/.gitignore @@ -163,3 +163,4 @@ cython_debug/ .flakeheaven_cache tests/artifacts/ -tests/artifacts/.gitkeep +mkdocs-material-insiders/ diff --git a/docs/decisions/diff-test-results.md b/docs/blog/diff-test-results.md similarity index 100% rename from docs/decisions/diff-test-results.md rename to docs/blog/diff-test-results.md diff --git a/docs/decisions/index.md b/docs/blog/index.md similarity index 100% rename from docs/decisions/index.md rename to docs/blog/index.md diff --git a/docs/decisions/parallelize-test-branches.md b/docs/blog/parallelize-test-branches.md similarity index 100% rename from docs/decisions/parallelize-test-branches.md rename to docs/blog/parallelize-test-branches.md diff --git a/docs/decisions/yaml-library.md b/docs/blog/yaml-library.md similarity index 100% rename from docs/decisions/yaml-library.md rename to docs/blog/yaml-library.md diff --git a/jeeves.py b/jeeves.py index 57f5d04..c57d3fa 100644 --- a/jeeves.py +++ b/jeeves.py @@ -157,3 +157,25 @@ def ci(): if newly_failed: raise typer.Exit(1) + + +def serve(): + """ + Serve the iolanta.tech site. + + The site will be available at http://localhost:9841 + """ + sh.mkdocs.serve( + '-a', 'localhost:6453', + _fg=True, + ) + + +def install_mkdocs_insiders(): + """Install Insiders version of `mkdocs-material` theme.""" + name = 'mkdocs-material-insiders' + + if not (Path.cwd() / name).is_dir(): + sh.gh.repo.clone(f'iolanta-tech/{name}') + + sh.pip.install('-e', name) diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..8fca27e --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,52 @@ +site_name: python-yaml-ld +site_url: https://python-yaml-ld.iolanta.tech +repo_url: https://github.com/iolanta-tech/python-yaml-ld +edit_uri: edit/master/docs/ +repo_name: iolanta-tech/python-yaml-ld +copyright: Copyright © 2024 iolanta.tech + +markdown_extensions: + - admonition + - codehilite + - attr_list + - def_list + - md_in_html + - pymdownx.superfences + - pymdownx.details + - footnotes + - pymdownx.tabbed: + alternate_style: true + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + + +plugins: + - search + - awesome-pages + - blogging: + dirs: + - blog + features: + tags: {} + time_format: '%d %b %Y' # The format used to display the time + - mkdocstrings: + handlers: + python: + import: + - https://docs.python-requests.org/en/master/objects.inv + - macros: + on_error_fail: true + +theme: + name: material + palette: + primary: orange + # custom_dir: overrides + features: + - navigation.sections + - navigation.indexes + - navigation.tabs + - navigation.tabs.sticky + - content.code.annotate + - content.action.edit diff --git a/poetry.lock b/poetry.lock index e25585d..c4b0a4a 100644 --- a/poetry.lock +++ b/poetry.lock @@ -110,6 +110,17 @@ soupsieve = ">1.2" html5lib = ["html5lib"] lxml = ["lxml"] +[[package]] +name = "bracex" +version = "2.4" +description = "Bash style brace expander." +optional = false +python-versions = ">=3.8" +files = [ + {file = "bracex-2.4-py3-none-any.whl", hash = "sha256:efdc71eff95eaff5e0f8cfebe7d01adf2c8637c8c92edaf63ef348c241a82418"}, + {file = "bracex-2.4.tar.gz", hash = "sha256:a27eaf1df42cf561fed58b7a8f3fdf129d1ea16a81e1fadd1d17989bc6384beb"}, +] + [[package]] name = "cachetools" version = "5.3.2" @@ -787,6 +798,20 @@ gitdb = ">=4.0.1,<5" [package.extras] test = ["black", "coverage[toml]", "ddt (>=1.1.1,!=1.4.3)", "mock", "mypy", "pre-commit", "pytest (>=7.3.1)", "pytest-cov", "pytest-instafail", "pytest-mock", "pytest-sugar", "sumtypes"] +[[package]] +name = "griffe" +version = "0.42.1" +description = "Signatures for entire Python programs. Extract the structure, the frame, the skeleton of your project, to generate API documentation or find breaking changes in your API." +optional = false +python-versions = ">=3.8" +files = [ + {file = "griffe-0.42.1-py3-none-any.whl", hash = "sha256:7e805e35617601355edcac0d3511cedc1ed0cb1f7645e2d336ae4b05bbae7b3b"}, + {file = "griffe-0.42.1.tar.gz", hash = "sha256:57046131384043ed078692b85d86b76568a686266cc036b9b56b704466f803ce"}, +] + +[package.dependencies] +colorama = ">=0.4" + [[package]] name = "idna" version = "3.6" @@ -1224,6 +1249,55 @@ watchdog = ">=2.0" i18n = ["babel (>=2.9.0)"] min-versions = ["babel (==2.9.0)", "click (==7.0)", "colorama (==0.4)", "ghp-import (==1.0)", "importlib-metadata (==4.3)", "jinja2 (==2.11.1)", "markdown (==3.2.1)", "markupsafe (==2.0.1)", "mergedeep (==1.3.4)", "packaging (==20.5)", "pathspec (==0.11.1)", "platformdirs (==2.2.0)", "pyyaml (==5.1)", "pyyaml-env-tag (==0.1)", "typing-extensions (==3.10)", "watchdog (==2.0)"] +[[package]] +name = "mkdocs-autorefs" +version = "1.0.1" +description = "Automatically link across pages in MkDocs." +optional = false +python-versions = ">=3.8" +files = [ + {file = "mkdocs_autorefs-1.0.1-py3-none-any.whl", hash = "sha256:aacdfae1ab197780fb7a2dac92ad8a3d8f7ca8049a9cbe56a4218cd52e8da570"}, + {file = "mkdocs_autorefs-1.0.1.tar.gz", hash = "sha256:f684edf847eced40b570b57846b15f0bf57fb93ac2c510450775dcf16accb971"}, +] + +[package.dependencies] +Markdown = ">=3.3" +markupsafe = ">=2.0.1" +mkdocs = ">=1.1" + +[[package]] +name = "mkdocs-awesome-pages-plugin" +version = "2.9.2" +description = "An MkDocs plugin that simplifies configuring page titles and their order" +optional = false +python-versions = ">=3.7" +files = [ + {file = "mkdocs_awesome_pages_plugin-2.9.2-py3-none-any.whl", hash = "sha256:9c795587695bd1ee85a8b7e43293005418df5a8b9ef296a3e628be427b693b4d"}, + {file = "mkdocs_awesome_pages_plugin-2.9.2.tar.gz", hash = "sha256:c3f7d366ecfe99b64524c49a84d8e13c576c19a918ea2e6f59bb486a259313af"}, +] + +[package.dependencies] +mkdocs = ">=1" +natsort = ">=8.1.0" +wcmatch = ">=7" + +[[package]] +name = "mkdocs-blogging-plugin" +version = "2.2.11" +description = "Mkdocs plugin that generates a blog index page sorted by creation date." +optional = false +python-versions = ">=3.6" +files = [ + {file = "mkdocs-blogging-plugin-2.2.11.tar.gz", hash = "sha256:91b3ebc1ee3870958a0f9304d985f73a8e170a1f8d17948488415fa1a4257b2e"}, + {file = "mkdocs_blogging_plugin-2.2.11-py3-none-any.whl", hash = "sha256:7e0f14e5a5d9d7fa106ee014b04a49e2fdb5ffe70a0026106dceb79930ba8ac2"}, +] + +[package.dependencies] +babel = ">=2.7.0" +GitPython = ">=3.1.18" +jinja2 = ">=2" +mkdocs = ">=1.0" + [[package]] name = "mkdocs-iolanta" version = "0.1.7" @@ -1302,6 +1376,48 @@ files = [ {file = "mkdocs_material_extensions-1.3.1.tar.gz", hash = "sha256:10c9511cea88f568257f960358a467d12b970e1f7b2c0e5fb2bb48cab1928443"}, ] +[[package]] +name = "mkdocstrings" +version = "0.24.1" +description = "Automatic documentation from sources, for MkDocs." +optional = false +python-versions = ">=3.8" +files = [ + {file = "mkdocstrings-0.24.1-py3-none-any.whl", hash = "sha256:b4206f9a2ca8a648e222d5a0ca1d36ba7dee53c88732818de183b536f9042b5d"}, + {file = "mkdocstrings-0.24.1.tar.gz", hash = "sha256:cc83f9a1c8724fc1be3c2fa071dd73d91ce902ef6a79710249ec8d0ee1064401"}, +] + +[package.dependencies] +click = ">=7.0" +Jinja2 = ">=2.11.1" +Markdown = ">=3.3" +MarkupSafe = ">=1.1" +mkdocs = ">=1.4" +mkdocs-autorefs = ">=0.3.1" +platformdirs = ">=2.2.0" +pymdown-extensions = ">=6.3" + +[package.extras] +crystal = ["mkdocstrings-crystal (>=0.3.4)"] +python = ["mkdocstrings-python (>=0.5.2)"] +python-legacy = ["mkdocstrings-python-legacy (>=0.2.1)"] + +[[package]] +name = "mkdocstrings-python" +version = "1.9.0" +description = "A Python handler for mkdocstrings." +optional = false +python-versions = ">=3.8" +files = [ + {file = "mkdocstrings_python-1.9.0-py3-none-any.whl", hash = "sha256:fad27d7314b4ec9c0359a187b477fb94c65ef561fdae941dca1b717c59aae96f"}, + {file = "mkdocstrings_python-1.9.0.tar.gz", hash = "sha256:6e1a442367cf75d30cf69774cbb1ad02aebec58bfff26087439df4955efecfde"}, +] + +[package.dependencies] +griffe = ">=0.37" +markdown = ">=3.3,<3.6" +mkdocstrings = ">=0.20" + [[package]] name = "more-itertools" version = "9.1.0" @@ -1371,6 +1487,21 @@ files = [ {file = "mypy_extensions-1.0.0.tar.gz", hash = "sha256:75dbf8955dc00442a438fc4d0666508a9a97b6bd41aa2f0ffe9d2f2725af0782"}, ] +[[package]] +name = "natsort" +version = "8.4.0" +description = "Simple yet flexible natural sorting in Python." +optional = false +python-versions = ">=3.7" +files = [ + {file = "natsort-8.4.0-py3-none-any.whl", hash = "sha256:4732914fb471f56b5cce04d7bae6f164a592c7712e1c85f9ef585e197299521c"}, + {file = "natsort-8.4.0.tar.gz", hash = "sha256:45312c4a0e5507593da193dedd04abb1469253b601ecaf63445ad80f0a1ea581"}, +] + +[package.extras] +fast = ["fastnumbers (>=2.0.0)"] +icu = ["PyICU (>=1.0.0)"] + [[package]] name = "owlrl" version = "6.0.2" @@ -2355,6 +2486,20 @@ files = [ [package.extras] watchmedo = ["PyYAML (>=3.10)"] +[[package]] +name = "wcmatch" +version = "8.5.1" +description = "Wildcard/glob file name matcher." +optional = false +python-versions = ">=3.8" +files = [ + {file = "wcmatch-8.5.1-py3-none-any.whl", hash = "sha256:24c19cedc92bc9c9e27f39db4e1824d72f95bd2cea32b254a47a45b1a1b227ed"}, + {file = "wcmatch-8.5.1.tar.gz", hash = "sha256:c0088c7f6426cf6bf27e530e2b7b734031905f7e490475fd83c7c5008ab581b3"}, +] + +[package.dependencies] +bracex = ">=2.1.1" + [[package]] name = "wemake-python-styleguide" version = "0.17.0" @@ -2390,4 +2535,4 @@ typing_extensions = ">=4.0,<5.0" [metadata] lock-version = "2.0" python-versions = ">=3.10,<4.0" -content-hash = "079ece0395df0c2c34749d76182d83e5df8de6b551d638f7948d05078870f3de" +content-hash = "d53394f634490aa263bcaeb62305da9f15055b8c90e0475e1364397fe46b9185" diff --git a/pyproject.toml b/pyproject.toml index 3a6cf31..e0fc013 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -22,6 +22,9 @@ types-pyyaml = "^6.0.12.11" rdflib-pyld-compat = "^0.1.0" lambdas = "^0.2.0" dominate = "^2.9.1" +mkdocs-awesome-pages-plugin = "^2.9.2" +mkdocs-blogging-plugin = "^2.2.11" +mkdocstrings-python = "^1.9.0" [build-system] requires = ["poetry-core"] From a79ddd34b441d9e01d401bd946e245311cfe70e5 Mon Sep 17 00:00:00 2001 From: Anatoly Scherbakov Date: Sat, 30 Mar 2024 21:54:31 +0400 Subject: [PATCH 2/3] Prettify home and blog --- docs/blog/diff-test-results.md | 1 + docs/blog/index.md | 11 +++++++ docs/blog/parallelize-test-branches.md | 1 + docs/blog/yaml-library.md | 1 + docs/index.md | 45 ++++++++++++++++++++++++++ 5 files changed, 59 insertions(+) diff --git a/docs/blog/diff-test-results.md b/docs/blog/diff-test-results.md index 0bbd161..e7ccec5 100644 --- a/docs/blog/diff-test-results.md +++ b/docs/blog/diff-test-results.md @@ -1,5 +1,6 @@ --- title: Diff test results +tags: [decision] --- ## Context diff --git a/docs/blog/index.md b/docs/blog/index.md index e69de29..1f554e1 100644 --- a/docs/blog/index.md +++ b/docs/blog/index.md @@ -0,0 +1,11 @@ +--- +exclude_from_blog: true +title: Blog +hide: + - navigation + - toc +--- + +# :material-message-text: Blog + +{{ blog_content }} diff --git a/docs/blog/parallelize-test-branches.md b/docs/blog/parallelize-test-branches.md index 380542a..f96c67b 100644 --- a/docs/blog/parallelize-test-branches.md +++ b/docs/blog/parallelize-test-branches.md @@ -1,4 +1,5 @@ --- +tags: [decision] is-blocked-by: diff-test-results.md title: Parallelize tests per branch in GitHub actions --- diff --git a/docs/blog/yaml-library.md b/docs/blog/yaml-library.md index be9b8a1..15618c8 100644 --- a/docs/blog/yaml-library.md +++ b/docs/blog/yaml-library.md @@ -1,4 +1,5 @@ --- +tags: [decision] context: rdfs:comment: To parse YAML-LD, we need to choose a YAML library from ones available. table:columns: diff --git a/docs/index.md b/docs/index.md index e69de29..1be4996 100644 --- a/docs/index.md +++ b/docs/index.md @@ -0,0 +1,45 @@ +--- +title: python-yaml-ld +hide: + - navigation + - toc +--- + +# YAML-LD implementation for Python + +![](logos/python-yaml-ld.png) + +A Python implementation for handling YAML-LD documents. + +## What is YAML-LD? + +YAML-LD is a YAML-based serialization for Linked Data, drawing inspiration from [JSON-LD](https://json-ld.org/). It aims to bring the ease of YAML along with the structured linked data principles of JSON-LD. The [YAML-LD specification](https://json-ld.github.io/yaml-ld/spec/) provides detailed information on the structure and usage of YAML-LD. + +## Installation + +```shell +pip install python-yaml-ld +``` + +## Functions + +### `yaml_ld.expand` + +Expands a given YAML-LD document into a standardized, expanded form following the [JSON-LD Expansion algorithm](https://www.w3.org/TR/json-ld11-api/#expansion). + +- **Parameters**: + - `document` (str | bytes | Document): The YAML-LD document to expand. + - `base` (str | None): The base IRI to use. + - `context` (Document | None): A context to expand with. + - `extract_all_scripts` (bool): True to extract all JSON-LD script elements from HTML, False to extract just the first. + - `mode` (ProcessingMode): The JSON-LD processing mode (defaults to JSON-LD 1.1). + - `document_loader` (DocumentLoader | None): The document loader to use. + +### `yaml_ld.to_rdf` + +Converts the YAML-LD document to RDF (quads) form, enabling interoperability with other RDF tools and systems. + +- **Parameters**: + - `document` (str | bytes | Document): The YAML-LD document to convert. + - `base` (str | None): The base IRI to use. + - `document_loader` (DocumentLoader | None): The document loader to use. From 96877bc9581ac2219ea5c7d14aef6b205c9fc399 Mon Sep 17 00:00:00 2001 From: Anatoly Scherbakov Date: Sat, 30 Mar 2024 21:57:26 +0400 Subject: [PATCH 3/3] Add gh action to deploy --- .github/workflows/deploy.yml | 26 ++++++++++++++++++++++++++ jeeves.py | 5 +++++ 2 files changed, 31 insertions(+) create mode 100644 .github/workflows/deploy.yml diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..c06fa2f --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,26 @@ +# https://blog.elmah.io/deploying-a-mkdocs-documentation-site-with-github-actions/ +on: + push: + branches: [master] + +jobs: + build: + name: Deploy to GitHub pages + runs-on: ubuntu-latest + environment: CI + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + with: + python-version: 3.11 + - run: pip install -q poetry + - run: poetry config virtualenvs.create false --local + - run: poetry install + - uses: actions/checkout@v3 + with: + repository: iolanta-tech/mkdocs-material-insiders + path: mkdocs-material-insiders + token: ${{ secrets.INSIDERS_TOKEN }} + + - run: j install-mkdocs-insiders + - run: j deploy-to-github-pages diff --git a/jeeves.py b/jeeves.py index c57d3fa..bcf781a 100644 --- a/jeeves.py +++ b/jeeves.py @@ -179,3 +179,8 @@ def install_mkdocs_insiders(): sh.gh.repo.clone(f'iolanta-tech/{name}') sh.pip.install('-e', name) + + +def deploy_to_github_pages(): + """Build the docs & deploy → gh-pages branch.""" + sh.mkdocs('gh-deploy', '--force', '--clean', '--verbose')