mkdocs-webis 0.1.0__tar.gz

mkdocs_webis-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

mkdocs_webis-0.1.0/.github/release.yml

@@ -0,0 +1,16 @@
+changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+    authors:
+      - octocat
+  categories:
+    - title: "🪲 Bug Fixes"
+      labels:
+        - bug
+    - title: "✨ New Features"
+      labels:
+        - enhancement
+    - title: "📄 Other Changes"
+      labels:
+        - "*"

mkdocs_webis-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,207 @@
+name: CI
+
+on:
+  push:
+
+jobs:
+  python-build:
+    name: "🏗️ Build Python wheels"
+    strategy:
+      matrix:
+        python:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Check-out"
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: "🧰 Install Python"
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: "🧰 Install dependencies"
+        run: pip install build twine
+      - name: "🏗️ Build Python wheels"
+        run: python -m build
+      - name: "🧪 Check package bundles"
+        run: twine check --strict dist/*
+      - name: "📤 Upload Python wheels"
+        uses: actions/upload-artifact@v7
+        if: matrix.python == '3.14'
+        with:
+          name: wheels
+          path: dist
+  python-code-check:
+    name: "🔍 Check Python code"
+    strategy:
+      matrix:
+        python:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Check-out"
+        uses: actions/checkout@v7
+      - name: "🧰 Install Python"
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: "🧰 Install dependencies"
+        run: pip install .[tests]
+      - name: "🔍 Check Python code"
+        run: ruff check .
+  python-typing:
+    name: "🔍 Check Python static typing"
+    strategy:
+      matrix:
+        python:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Check-out"
+        uses: actions/checkout@v7
+      - name: "🧰 Install Python"
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: "🧰 Install dependencies"
+        run: pip install .[tests]
+      - name: "🔍 Check Python static typing"
+        run: mypy .
+  python-test:
+    name: "🧪 Test Python code"
+    strategy:
+      matrix:
+        python:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Check-out"
+        uses: actions/checkout@v7
+      - name: "🧰 Install Python"
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: "🧰 Install dependencies"
+        run: pip install .[tests]
+      - name: "🧪 Test Python code"
+        run: pytest --cov --cov-report=xml .
+      - name: "📤 Upload coverage to Codecov"
+        uses: codecov/codecov-action@v7
+        if: matrix.python == '3.14'
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+  docs-build:
+    name: "📖 Build documentation"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Check-out"
+        uses: actions/checkout@v7
+      - name: "🧰 Install Python"
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: "🧰 Install dependencies"
+        run: pip install .
+      - name: "📖 Build documentation"
+        run: mkdocs build --strict
+        env:
+          DISABLE_MKDOCS_2_WARNING: "true"
+      - name: "📤 Upload documentation"
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+  docs-deploy:
+    name: "🚀 Deploy documentation to GitHub Pages"
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs:
+      - docs-build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    concurrency:
+      group: github-pages
+      cancel-in-progress: false
+    steps:
+      - name: "🚀 Deploy to GitHub Pages"
+        id: deployment
+        uses: actions/deploy-pages@v5
+  python-publish:
+    name: "🚀 Publish Python wheels"
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+    needs:
+      - python-build
+      - python-code-check
+      - python-typing
+      - python-test
+      - docs-build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: "📥 Check-out"
+        uses: actions/checkout@v7
+      - name: "📥 Download Python wheels"
+        uses: actions/download-artifact@v8
+        with:
+          name: wheels
+          path: dist
+      - name: "🚀 Publish Python wheels"
+        uses: pypa/gh-action-pypi-publish@release/v1
+  github-release:
+    name: "🚀 Create GitHub release"
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+    needs:
+      - python-build
+      - python-code-check
+      - python-typing
+      - python-test
+      - docs-build
+      - python-publish
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Check-out"
+        uses: actions/checkout@v7
+      - name: "📥 Download Python wheels"
+        uses: actions/download-artifact@v8
+        with:
+          name: wheels
+          path: dist
+      - name: "🚀 Create GitHub release"
+        uses: softprops/action-gh-release@v3
+        with:
+          name: Release ${{ github.ref_name }}
+          files: dist/*
+          fail_on_unmatched_files: true
+          draft: false
+          prerelease: false
+          generate_release_notes: true

mkdocs_webis-0.1.0/.gitignore

@@ -0,0 +1,169 @@
+# Created by https://www.toptal.com/developers/gitignore/api/python,visualstudiocode,intellij
+# Edit at https://www.toptal.com/developers/gitignore?templates=python,visualstudiocode,intellij
+
+### Intellij ###
+.idea
+*.iml
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+### VisualStudioCode ###
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+*.code-workspace
+
+# Local History for Visual Studio Code
+.history/
+
+### VisualStudioCode Patch ###
+# Ignore all local history of files
+.history
+.ionide
+
+# Support for Project snippet scope
+!.vscode/*.code-snippets
+
+# End of https://www.toptal.com/developers/gitignore/api/python,visualstudiocode,intellij
+
+venv-*/

mkdocs_webis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan Heinrich Merker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocs_webis-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: mkdocs-webis
+Version: 0.1.0
+Summary: Webis style and BibTeX citations for MkDocs Material.
+Author-email: Jan Heinrich Merker <heinrich.merker@uni-jena.de>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/webis-de/mkdocs-webis
+Project-URL: Bug Tracker, https://github.com/webis-de/mkdocs-webis/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: MkDocs
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Documentation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mkdocs~=1.6
+Requires-Dist: mkdocs-material~=9.6
+Requires-Dist: bibtexparser~=2.0
+Requires-Dist: pylatexenc~=2.10
+Provides-Extra: tests
+Requires-Dist: mypy<3.0,>=1.13; extra == "tests"
+Requires-Dist: pytest<10.0,>=8.3; extra == "tests"
+Requires-Dist: pytest-cov<8.0,>=6.3; extra == "tests"
+Requires-Dist: ruff<0.18.0,>=0.12.7; extra == "tests"
+Dynamic: license-file
+
+<!-- markdownlint-disable MD041 -->
+
+[![PyPi](https://img.shields.io/pypi/v/mkdocs-webis?style=flat-square)](https://pypi.org/project/mkdocs-webis/)
+[![CI](https://img.shields.io/github/actions/workflow/status/webis-de/mkdocs-webis/ci.yml?branch=main&style=flat-square)](https://github.com/webis-de/mkdocs-webis/actions/workflows/ci.yml)
+[![Code coverage](https://img.shields.io/codecov/c/github/webis-de/mkdocs-webis?style=flat-square)](https://codecov.io/github/webis-de/mkdocs-webis/)
+[![Python](https://img.shields.io/pypi/pyversions/mkdocs-webis?style=flat-square)](https://pypi.org/project/mkdocs-webis/)
+[![Issues](https://img.shields.io/github/issues/webis-de/mkdocs-webis?style=flat-square)](https://github.com/webis-de/mkdocs-webis/issues)
+[![Commit activity](https://img.shields.io/github/commit-activity/m/webis-de/mkdocs-webis?style=flat-square)](https://github.com/webis-de/mkdocs-webis/commits)
+[![Downloads](https://img.shields.io/pypi/dm/mkdocs-webis?style=flat-square)](https://pypi.org/project/mkdocs-webis/)
+[![License](https://img.shields.io/github/license/webis-de/mkdocs-webis?style=flat-square)](LICENSE)
+
+# 📘 mkdocs-webis
+
+Webis style and BibTeX citations for [MkDocs Material](https://squidfunk.github.io/mkdocs-material/).
+
+This MkDocs plugin...
+
+- ... styles your documentation like the [Webis homepage](https://webis.de/) (a dark gray navigation bar with the Webis logo, the "Product Sans" and "Noto Sans" fonts, plain headings, blue links and buttons, flat tables, and a light gray footer),
+- ... lets you cite references from a BibTeX file with `[@key]` or `[@key1, @key2]`, rendered as gray author–year citations like "[Fang et al., 2004]", and appends a list of the cited references (including their BibTeX) to each page.
+
+The [documentation](https://webis-de.github.io/mkdocs-webis/) is rendered with the plugin itself, so it doubles as a demo.
+
+## Installation
+
+Install the package from PyPI:
+
+```shell
+pip install mkdocs-webis
+```
+
+## Usage
+
+Enable the plugin in your `mkdocs.yml` (together with the [Material](https://squidfunk.github.io/mkdocs-material/) theme):
+
+```yaml
+theme:
+  name: material
+
+plugins:
+  - webis:
+      # Optional: BibTeX file in your docs directory.
+      bibliography: references.bib
+```
+
+### Citations
+
+With a `bibliography` configured, cite references by their BibTeX keys:
+
+```markdown
+Axioms are formal constraints on retrieval models [@fang2004formal].
+Some studies use axioms for re-ranking [@hagen2016axiomatic, @bondarenko2022axiomatic].
+```
+
+Citations are rendered as gray author–year links in brackets (e.g., "[Fang et al., 2004]" or "[Hagen et al., 2016; Bondarenko et al., 2022]"), like on the Webis slides.
+They link to a "References" section at the bottom of the same page, which lists all references cited on that page.
+Multiple keys are separated by commas or semicolons.
+
+We recommend copying BibTeX entries from [DBLP](https://dblp.org/).
+
+### Style Elements
+
+Besides styling the standard Material elements, the stylesheet provides a few CSS classes:
+
+```markdown
+# Page Title
+
+<p class="subtitle">A gray subtitle below the page title.</p>
+
+<span class="badge">TFC1</span> — a small label, e.g., for names or acronyms.
+```
+
+The colors of webis.de are available as CSS variables (e.g., `var(--webis-blue)`, `var(--webis-red)`) for your own stylesheets.
+See the [style elements](https://webis-de.github.io/mkdocs-webis/style/) for how all elements look.
+
+## Development
+
+To build this package and contribute to its development you need to install the `build`, `setuptools` and `wheel` packages:
+
+```shell
+pip install build setuptools wheel
+```
+
+(On most systems, these packages are already pre-installed.)
+
+### Development installation
+
+Install package and test dependencies:
+
+```shell
+pip install -e .[tests]
+```
+
+### Testing
+
+Verify your changes against the test suite to verify.
+
+```shell
+ruff check .  # Code format, LINT, and security
+mypy .        # Static typing
+pytest .      # Unit tests
+```
+
+Please also add tests for your newly developed code.
+
+### Documentation and demo
+
+The documentation in [`docs/`](docs/) uses the plugin itself, including a [page with all style elements](docs/style.md) and [citations](docs/citations.md).
+Preview it locally to check changes to the style or the citations:
+
+```shell
+mkdocs serve
+```
+
+### Build wheels
+
+Wheels for this package can be built with:
+
+```shell
+python -m build
+```
+
+## Support
+
+If you have any problems using this package, please file an [issue](https://github.com/webis-de/mkdocs-webis/issues/new).
+We're happy to help!
+
+## License
+
+This repository is released under the [MIT license](LICENSE).