diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 505100b..12e2ac1 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -4,7 +4,7 @@ on: workflow_dispatch: push: tags: - - 'v[0-9]+.[0-9]+.[0-9]+' + - "v[0-9]+.[0-9]+.[0-9]+" jobs: test: @@ -18,7 +18,7 @@ jobs: environment: release runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 with: fetch-depth: 0 diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index 1a3602f..d889837 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -3,7 +3,7 @@ on: workflow_dispatch: push: tags: - - 'v[0-9]+.[0-9]+.[0-9]+' + - "v[0-9]+.[0-9]+.[0-9]+" permissions: contents: read @@ -22,10 +22,10 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 - - name: Set up Python 3.11 + - name: Set up Python 3.12 uses: actions/setup-python@v5 with: - python-version: 3.11 + python-version: 3.12 - name: Install dependencies run: | python -m pip install --upgrade pip diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 0b2fb37..9328476 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -19,20 +19,20 @@ jobs: os: [ubuntu-latest, macos-latest, windows-latest] steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 - with: - python-version: 3.9 - - uses: actions/setup-python@v5 - with: - python-version: 3.11 - - - name: install requirements - run: python -m pip install nox pre-commit + - uses: actions/checkout@v6 + - uses: actions/setup-python@v6 + with: + python-version: | + 3.10 + 3.11 + 3.12 - - name: run pre-commit - if: ${{ matrix.os == 'ubuntu-latest' }} - run: pre-commit run --all --show-diff-on-failure + - name: install requirements + run: python -m pip install nox pre-commit - - name: run tests - run: nox + - name: run pre-commit + if: ${{ matrix.os == 'ubuntu-latest' }} + run: pre-commit run --all --show-diff-on-failure + + - name: run tests + run: nox diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4a92bbc..487befb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -Thanks for considering a contribution to fillname. ❤️ +Thanks for considering a contribution to fillname. ## How to get help or discuss possible contributions @@ -16,7 +16,7 @@ To avoid duplicating issues, please search our [issue tracker][issues] and our changes. - Submit a pull request to the master branch with your changes. - Respond to feedback on your pull request. -- If everything is fine your pull request is merged. 🥳 +- If everything is fine your pull request is merged! ## License diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 40addce..dc7e366 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,5 +1,11 @@ # Development +To install the project in development mode, use the following command: + +```bash +pip install -e . +``` + To improve code quality, we use [nox] to run linters, type checkers, unit tests, and more. We recommend installing nox using [pipx] to have it available globally. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..25d3fe0 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,16 @@ +* Getting Started + * [Quick Start Guide](use/quick-start.md) + * [Installation](use/installation.md) + * [Help](use/help.md) +* Reference + * [Reference](reference/index.md) + * [Encodings](reference/encodings/index.md) + * [API](reference/api/index.md) + * [CLI](reference/cli/index.md) +* Examples + * [Examples](examples/index.md) +* Community + * [Contributing](community/CONTRIBUTING.md) + * [Changes](community/CHANGES.md) + * [Development](community/DEVELOPMENT.md) + * [Deployment](community/DEPLOYMENT.md) diff --git a/docs/_custom/css/extra.css b/docs/_custom/css/extra.css index b2264f2..5b6ceac 100644 --- a/docs/_custom/css/extra.css +++ b/docs/_custom/css/extra.css @@ -1,16 +1,72 @@ +/* ============================================================ + Brand colors + ============================================================ */ + :root { --md-primary-fg-color: #6495ED; } +[data-md-color-scheme="default"] .md-header, +[data-md-color-scheme="default"] .md-tabs, [data-md-color-scheme="slate"] .md-header, [data-md-color-scheme="slate"] .md-tabs { - --md-primary-fg-color: #253758; + --md-primary-fg-color: #2E3360; +} + +[data-md-color-scheme="default"] .md-nav--primary .md-nav__title, +[data-md-color-scheme="slate"] .md-nav--primary .md-nav__title { + background-color: #2E3360; +} + + +/* ============================================================ + Code highlight colors + ============================================================ */ + +[data-md-color-scheme="default"] { + --md-code-hl-number-color: hsl(11, 80%, 40%); + --md-code-hl-special-color: hsl(340, 75%, 45%); + --md-code-hl-function-color: hsl(271, 55%, 45%); + --md-code-hl-constant-color: hsl(220, 70%, 45%); + --md-code-hl-keyword-color: var(--md-primary-fg-color); + --md-code-hl-string-color: hsl(160, 50%, 30%); + --md-code-hl-name-color: hsl(43, 90%, 32%); + --md-code-hl-operator-color: hsl(0, 0%, 30%); + --md-code-hl-punctuation-color: hsl(271, 45%, 45%); + --md-code-hl-comment-color: hsl(210, 15%, 50%); + --md-code-hl-generic-color: hsl(210, 15%, 45%); + --md-code-hl-variable-color: hsl(24, 70%, 38%); +} + +[data-md-color-scheme="slate"] { + --md-code-hl-number-color: hsl(11, 85%, 68%); + --md-code-hl-special-color: hsl(340, 82%, 72%); + --md-code-hl-function-color: hsl(271, 70%, 78%); + --md-code-hl-constant-color: hsl(220, 80%, 75%); + --md-code-hl-keyword-color: #6fa3f7; + --md-code-hl-string-color: hsl(160, 55%, 60%); + --md-code-hl-name-color: hsl(43, 100%, 65%); + --md-code-hl-operator-color: hsl(0, 0%, 72%); + --md-code-hl-punctuation-color: hsl(271, 60%, 78%); + --md-code-hl-comment-color: hsl(210, 15%, 55%); + --md-code-hl-generic-color: hsl(210, 15%, 62%); + --md-code-hl-variable-color: hsl(24, 80%, 68%); } + +/* ============================================================ + Layout + ============================================================ */ + .md-grid { max-width: 1350px; } + +/* ============================================================ + Header + ============================================================ */ + .md-header__title { font-size: 1.2rem; height: 2.5rem; @@ -19,7 +75,6 @@ } .md-header__button.md-logo { - /* margin-left: 30; */ padding-bottom: 0.8rem; } @@ -28,3 +83,83 @@ height: 1.5rem; width: 1.5rem; } + + +/* ============================================================ + Admonitions + ============================================================ */ + +.md-typeset .admonition, +.md-typeset details { + border-width: 0; + border-left-width: 3px; +} + +/* info / note / abstract / tip — primary color */ +.md-typeset .info>.admonition-title, +.md-typeset .info>summary, +.md-typeset .note>.admonition-title, +.md-typeset .note>summary, +.md-typeset .abstract>.admonition-title, +.md-typeset .abstract>summary, +.md-typeset .tip>.admonition-title, +.md-typeset .tip>summary { + border-color: var(--md-primary-fg-color); + background-color: color-mix(in srgb, var(--md-primary-fg-color) 10%, transparent); +} + +.md-typeset .admonition.info, +.md-typeset details.info, +.md-typeset .admonition.note, +.md-typeset details.note, +.md-typeset .admonition.abstract, +.md-typeset details.abstract, +.md-typeset .admonition.tip, +.md-typeset details.tip { + border-color: var(--md-primary-fg-color); +} + +.md-typeset .info>.admonition-title::before, +.md-typeset .info>summary::before, +.md-typeset .note>.admonition-title::before, +.md-typeset .note>summary::before, +.md-typeset .abstract>.admonition-title::before, +.md-typeset .abstract>summary::before, +.md-typeset .tip>.admonition-title::before, +.md-typeset .tip>summary::before { + background-color: var(--md-primary-fg-color); +} + +/* question — yellow */ +.md-typeset .question>.admonition-title, +.md-typeset .question>summary { + border-color: #A8AD00; + background-color: color-mix(in srgb, #A8AD00 10%, transparent); +} + +.md-typeset .admonition.question, +.md-typeset details.question { + border-color: #A8AD00; +} + +.md-typeset .question>.admonition-title::before, +.md-typeset .question>summary::before { + background-color: #A8AD00; +} + +/* success — green */ +.md-typeset .success>.admonition-title, +.md-typeset .success>summary { + border-color: #2E7D32; + background-color: color-mix(in srgb, #2E7D32 10%, transparent); +} + +.md-typeset .admonition.success, +.md-typeset details.success { + border-color: #2E7D32; +} + +.md-typeset .success>.admonition-title::before, +.md-typeset .success>summary::before { + background-color: #2E7D32; +} diff --git a/docs/_custom/overrides/.icons/potassco-full-logo.svg b/docs/_custom/overrides/.icons/potassco-full-logo.svg deleted file mode 100644 index b5c199c..0000000 --- a/docs/_custom/overrides/.icons/potassco-full-logo.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - diff --git a/docs/_custom/overrides/.icons/potassco-logo.svg b/docs/_custom/overrides/.icons/potassco-logo.svg index fde2a4a..cf24ead 100644 --- a/docs/_custom/overrides/.icons/potassco-logo.svg +++ b/docs/_custom/overrides/.icons/potassco-logo.svg @@ -1,3 +1,12 @@ - - + + + + + + + + + diff --git a/docs/assets/images/potassco-full-logo.svg b/docs/assets/images/potassco-full-logo.svg deleted file mode 100644 index b5c199c..0000000 --- a/docs/assets/images/potassco-full-logo.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - diff --git a/docs/assets/images/potassco-logo-dark.svg b/docs/assets/images/potassco-logo-dark.svg deleted file mode 100644 index e6706af..0000000 --- a/docs/assets/images/potassco-logo-dark.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - diff --git a/docs/assets/images/potassco-logo.svg b/docs/assets/images/potassco-logo.svg index fde2a4a..42a0059 100644 --- a/docs/assets/images/potassco-logo.svg +++ b/docs/assets/images/potassco-logo.svg @@ -1,3 +1,10 @@ - - + + + + + + + + + diff --git a/docs/community/CHANGES.md b/docs/community/CHANGES.md deleted file mode 120000 index 8980b4a..0000000 --- a/docs/community/CHANGES.md +++ /dev/null @@ -1 +0,0 @@ -../../CHANGES.md \ No newline at end of file diff --git a/docs/community/CHANGES.md b/docs/community/CHANGES.md new file mode 100644 index 0000000..a0929b9 --- /dev/null +++ b/docs/community/CHANGES.md @@ -0,0 +1,11 @@ +--- +icon: material/update +--- + +--8<-- "CHANGES.md" + + +!!! info "Release Notes" + + For a detailed list of changes, please check the GitHub [releases](https://github.com/potassco/fillname/releases) + and [tags](https://github.com/potassco/fillname/tags). diff --git a/docs/community/CONTRIBUTING.md b/docs/community/CONTRIBUTING.md deleted file mode 120000 index f939e75..0000000 --- a/docs/community/CONTRIBUTING.md +++ /dev/null @@ -1 +0,0 @@ -../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/community/CONTRIBUTING.md b/docs/community/CONTRIBUTING.md new file mode 100644 index 0000000..a612612 --- /dev/null +++ b/docs/community/CONTRIBUTING.md @@ -0,0 +1,5 @@ +--- +icon: material/hand-heart +--- + +--8<-- "CONTRIBUTING.md" diff --git a/docs/community/DEPLOYMENT.md b/docs/community/DEPLOYMENT.md deleted file mode 120000 index efafc4c..0000000 --- a/docs/community/DEPLOYMENT.md +++ /dev/null @@ -1 +0,0 @@ -../../DEPLOYMENT.md \ No newline at end of file diff --git a/docs/community/DEPLOYMENT.md b/docs/community/DEPLOYMENT.md new file mode 100644 index 0000000..0be556f --- /dev/null +++ b/docs/community/DEPLOYMENT.md @@ -0,0 +1,5 @@ +--- +icon: material/rocket +--- + +--8<-- "DEPLOYMENT.md" diff --git a/docs/community/DEVELOPMENT.md b/docs/community/DEVELOPMENT.md deleted file mode 120000 index 62bb95a..0000000 --- a/docs/community/DEVELOPMENT.md +++ /dev/null @@ -1 +0,0 @@ -../../DEVELOPMENT.md \ No newline at end of file diff --git a/docs/community/DEVELOPMENT.md b/docs/community/DEVELOPMENT.md new file mode 100644 index 0000000..3107d43 --- /dev/null +++ b/docs/community/DEVELOPMENT.md @@ -0,0 +1,5 @@ +--- +icon: material/code-braces-box +--- + +--8<-- "DEVELOPMENT.md" diff --git a/docs/community/help.md b/docs/community/help.md deleted file mode 100644 index dc9121b..0000000 --- a/docs/community/help.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -icon: material/help-circle ---- - -# Help - -## First steps - -!!! tip - "Search bar" Use the search bar from this documentation page to find - what you are looking for. - -!!! tip - "Look at the examples" The examples tab has might give you some insides - into how to use the tool. - -!!! tip - "Mailing list" Our [mailing list][mailing_list] might have some - information about your issue. Search for questions made by previous users of - the potassco tools. You can also [subscribe] to this list to get updates and - join the community. - -## Further help - -!!! question "Open an Issue" - Open an [issue][new_issue] describing your problem. - -!!! warning - To avoid duplicating issues, please search our [issue tracker][issues] and our - [mailing list][mailing_list] before filing a new issue. - -!!! question "Reach out in the mailing list" - Send an email to the list with your issue. - -## General ASP support - -- Take a look at the [support page][support_page] of Potassco. - -[mailing_list]: https://sourceforge.net/p/potassco/mailman/potassco-users/ -[subscribe]: https://sourceforge.net/projects/potassco/lists/potassco-users/ -[support_page]: https://potassco.org/support/ -[new_issue]: https://github.com/potassco/fillname/issues/new -[issues]: https://github.com/potassco/fillname/issues diff --git a/docs/community/index.md b/docs/community/index.md deleted file mode 100644 index d230d56..0000000 --- a/docs/community/index.md +++ /dev/null @@ -1,29 +0,0 @@ -# Community - -Welcome to the **Community** hub! 🚀 - -This is the central place for everything related to contributing, staying -up-to-date, and engaging with our project. Whether you’re here to collaborate, -explore the latest changes, or find support, we’ve got you covered. - -## What’s Inside - -- **Changelog:** Stay informed about the latest updates and improvements. -- **Contributing:** Learn how to get involved and make an impact on the - project. -- **Development:** Dive into the technical details of how our system works. -- **Deployment:** Get guidance on setting up and deploying the system in - various environments. -- **Help:** Access resources to get answers to your questions. - -## How You Can Contribute - -1. **Report Issues:** Found a bug? Let us know! -1. **Share Ideas:** Help us shape the future by suggesting features. -1. **Collaborate:** Submit pull requests and contribute code. - -Your participation keeps our project thriving. Thank you for being part of our -community! - -!!! info - *fillname* is part of the [Potassco](https://potassco.org) suite. diff --git a/docs/examples/index.md b/docs/examples/index.md index bff9d10..28ac848 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -5,7 +5,7 @@ hide: # Examples -Welcome to the **Examples** section of our documentation! 🎉 +Welcome to the **Examples** section of our documentation! Here, you'll find a comprehensive set of practical examples designed to help you get the most out of our system. Whether you're a first-time user or an diff --git a/docs/getting_started.md b/docs/getting_started.md deleted file mode 100644 index 96aae86..0000000 --- a/docs/getting_started.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -hide: - - navigation ---- - -# Getting started - -## Installation - -=== "Pip" - - ```console - pip install fillname - ``` - -=== "Development mode" - - ```console - git clone https://github.com/potassco/fillname.git/ - cd fillname - pip install -e .[all] - ``` - - !!! warning - Use only for development purposes - -## Usage - -### Command line interface - -Details about the command line usage can be found with: - -```console -fillname -h -``` diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md new file mode 100644 index 0000000..1281152 --- /dev/null +++ b/docs/reference/cli/index.md @@ -0,0 +1,14 @@ +--- +icon: material/code-greater-than +--- + +# CLI + +You can access all of fillname's features over the commad-line interface (CLI). +This page details all available features and how to use them. + +## CLI Specification + +```bash +fillname --help +``` diff --git a/docs/reference/index.md b/docs/reference/index.md index d21c7fe..2415d2d 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,19 +1,13 @@ # Reference -Welcome to the **Reference** section! 📚 +Welcome to the **Reference** section! This section contains detailed documentation and technical information about the system. It’s designed for those who want to explore the inner workings, learn about specific components, or access essential resources. -## What’s Inside - -- **API Documentation:** Comprehensive details on general classes. -- **ASP Encodings:** Explore the encodings used in our system. -- **Problem Specifications:** Detailed description and definitions of the - problem. - +!!! tip -Use this section to find the information you need, whether you’re debugging, -extending functionality, or learning more about the system. + Use this section to find the information you need, whether you’re debugging, + extending functionality, or learning more about the system. diff --git a/docs/reference/problem/index.md b/docs/reference/problem/index.md deleted file mode 100644 index 685afb9..0000000 --- a/docs/reference/problem/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -icon: material/head-dots-horizontal ---- - -# Problem specification diff --git a/docs/use/help.md b/docs/use/help.md new file mode 100644 index 0000000..2e9843c --- /dev/null +++ b/docs/use/help.md @@ -0,0 +1,52 @@ +--- +icon: material/help-circle +--- + + +## FAQ + + +## General Tips + +!!! tip "Search bar" + Use the search bar from this documentation page to find + what you are looking for. + +!!! tip "Examples" + The examples tab might give you some insights + into how to use the tool. + +!!! tip "Debug logs" + Use debug logs to inspect the internal process with `--log debug` + +## Further help + + +!!! tip "Open an Issue" + Open an [issue][new_issue] describing your problem. + +!!! tip "Mailing list" + Our [mailing list][mailing_list] might have some + information about your issue. Search for questions made by previous users of + the potassco tools. + + You can also [subscribe] to this list to get updates and + join the community. Or send an email to the list with your issue. + +!!! warning "Search for existing issues" + To avoid duplicating issues, please search our [issue tracker][issues] and our + [mailing list][mailing_list] before filing a new issue. + + + +## General ASP support + +!!! tip "Support page" + + Take a look at the [support page][support_page] of Potassco. + +[mailing_list]: https://sourceforge.net/p/potassco/mailman/potassco-users/ +[subscribe]: https://sourceforge.net/projects/potassco/lists/potassco-users/ +[support_page]: https://potassco.org/support/ +[new_issue]: https://github.com/potassco/asplain/issues/new +[issues]: https://github.com/potassco/asplain/issues diff --git a/docs/use/installation.md b/docs/use/installation.md new file mode 100644 index 0000000..6ad671e --- /dev/null +++ b/docs/use/installation.md @@ -0,0 +1,21 @@ +--- +icon: "material/wrench" +--- + +# Installation + +Install via pip: + +```console +pip install fillname +``` + +----- + +A successful installation will make the `fillname` command available in your terminal. You can check the installation by running: + +```console +fillname -h +``` + +This will display the help message with available options and usage instructions, for detailed CLI information refer to the [CLI documentation](../reference/cli/index.md). diff --git a/docs/use/quick-start.md b/docs/use/quick-start.md new file mode 100644 index 0000000..5b644ca --- /dev/null +++ b/docs/use/quick-start.md @@ -0,0 +1,7 @@ +--- +icon: "material/rocket-launch" +--- + +# Quick Start Guide + +--8<-- "README.md:2:" diff --git a/mkdocs.yml b/mkdocs.yml index ec15967..4649302 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,7 +18,7 @@ theme: name: material logo: assets/images/potassco-logo.svg custom_dir: docs/_custom/overrides - favicon: assets/images/potassco-logo-dark.svg + favicon: assets/images/potassco-logo.svg features: - header.autohide - navigation.instant @@ -60,21 +60,33 @@ theme: extra: social: - - icon: fontawesome/brands/github - link: https://github.com/potassco/fillname - icon: potassco-logo link: https://potassco.org + - icon: fontawesome/brands/github + link: https://github.com/potassco/fillname + - icon: fontawesome/brands/x-twitter + link: https://x.com/potassco + - icon: fontawesome/brands/facebook + link: https://www.facebook.com/potassco + - icon: fontawesome/brands/youtube + link: https://www.youtube.com/@Potassco-live generator: false markdown_extensions: - admonition - pymdownx.details - pymdownx.keys + - pymdownx.highlight: + use_pygments: true + pygments_lang_class: true - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format + - name: lp + class: lp + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true - pymdownx.emoji: @@ -96,6 +108,8 @@ markdown_extensions: plugins: - search - autorefs + - literate-nav: + nav_file: SUMMARY.md - mkdocstrings: handlers: python: @@ -112,20 +126,3 @@ plugins: show_inherited_detail: true show_inherited_detail_toc: true show_inherited_detail_tree: true - -nav: - - Home: index.md - - Getting Started: getting_started.md - - Examples: examples/index.md - - Reference: - - reference/index.md - - Problem: reference/problem/index.md - - Encodings: reference/encodings/index.md - - API: reference/api/index.md - - Community: - - community/index.md - - Help: community/help.md - - Changes: community/CHANGES.md - - Contributing: community/CONTRIBUTING.md - - Development: community/DEVELOPMENT.md - - Deployment: community/DEPLOYMENT.md diff --git a/pyproject.toml b/pyproject.toml index 075205f..d573c6e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,7 +19,15 @@ format = ["black", "isort", "autoflake"] lint_pylint = ["pylint"] typecheck = ["types-setuptools", "mypy"] test = ["coverage[toml]"] -doc = ["mkdocs", "mkdocs-material", "mkdocstrings[python]", "mkdoclingo"] +doc = [ + "mkdocs", + "mkdocs-material", + "mkdocstrings>=1.0.4", + "mkdocstrings-python>=2.0", + "mkdoclingo>=1.4.0", + "mkdocs-literate-nav", + "pygments_clingo", +] dev = ["fillname[test,typecheck,lint_pylint]"] [project.scripts]