Merge pull request #39 from iolanta-tech/38-start-docs-site

38 start docs site

Author: anatoly-scherbakov

.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

.gitignore

@@ -163,3 +163,4 @@ cython_debug/
 .flakeheaven_cache
 tests/artifacts/
 -tests/artifacts/.gitkeep
+mkdocs-material-insiders/

docs/decisions/diff-test-results.md renamed to docs/blog/diff-test-results.md

@@ -1,5 +1,6 @@
 ---
 title: Diff test results
+tags: [decision]
 ---
 
 ## Context

docs/blog/index.md

@@ -0,0 +1,11 @@
+---
+exclude_from_blog: true
+title: Blog
+hide:
+    - navigation
+    - toc
+---
+
+# :material-message-text: Blog
+
+{{ blog_content }}

docs/decisions/parallelize-test-branches.md renamed to 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
 ---

docs/decisions/yaml-library.md renamed to 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:

docs/decisions/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.

docs/index.md

@@ -157,3 +157,30 @@ 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)
+
+
+def deploy_to_github_pages():
+    """Build the docs & deploy → gh-pages branch."""
+    sh.mkdocs('gh-deploy', '--force', '--clean', '--verbose')

jeeves.py

@@ -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

mkdocs.yml

@@ -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"]