clindocs 1.5.1__tar.gz

clindocs-1.5.1/.envrc

@@ -0,0 +1,10 @@
+# automatically activate dev environment when in project tree using direnv.
+ACT=.nox/dev/bin/activate
+
+if [ -e $ACT ]
+then
+    source $ACT
+else
+    echo "Activation script ${ACT} not found for dev environment.
+Run nox -s dev to install dev environment"
+fi

clindocs-1.5.1/.github/workflows/deploy.yml

@@ -0,0 +1,46 @@
+name: deploy to pypi
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  deploy:
+    name: deploy
+    permissions:
+      id-token: write
+    environment: release
+    runs-on: ubuntu-latest
+    if: ${{ endsWith(github.event.base_ref, 'master') }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: install build dependencies
+        run: python3 -m pip install build
+
+      - name: build package
+        run: python3 -m build --sdist --wheel --outdir dist/
+
+      - name: upload package
+        uses: actions/upload-artifact@v4
+        with:
+          name: package
+          path: dist/
+
+      - name: publish package (pypi)
+        if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: publish package (test.pypi)
+        if: ${{ github.event_name == 'workflow_dispatch' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: "https://test.pypi.org/legacy/"

clindocs-1.5.1/.github/workflows/doc.yml

@@ -0,0 +1,49 @@
+name: Deploy Documentation
+on:
+  push:
+    branches:
+      - master
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[doc]
+      - name: Build the documentation
+        run: mkdocs build
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "./site"
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ format('{0}docs/', steps.deployment.outputs.page_url) }}
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

clindocs-1.5.1/.github/workflows/test.yml

@@ -0,0 +1,41 @@
+name: run CI test
+
+on:
+  push:
+    branches: [devel, main, master, wip]
+  pull_request:
+  workflow_call:
+
+env:
+  FORCE_COLOR: "3"
+
+jobs:
+  build:
+    name: test on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        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
+        python -m pip install -e .[dev]
+
+
+    - name: run pre-commit
+      if: ${{ matrix.os == 'ubuntu-latest' }}
+      run: pre-commit run --all --show-diff-on-failure
+
+    - name: run tests
+      run: nox

clindocs-1.5.1/.gitignore

@@ -0,0 +1,39 @@
+# Editors
+.vscode/
+*~
+\#*\#
+.\#*
+
+# Mac/OSX
+.DS_Store
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+.pytest_cache/
+
+# pyenv
+.python-version
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+*egg-info*
+
+# unclassified
+dist
+build
+.coverage
+_build
+_autosummary
+site
+
+.conda

clindocs-1.5.1/.pre-commit-config.yaml

@@ -0,0 +1,74 @@
+repos:
+  - repo: https://github.com/myint/autoflake
+    rev: v2.3.1
+    hooks:
+    - id: autoflake
+      args: ["--in-place",  "--imports=constraint_handler_benchmarks", "--ignore-init-module-imports", "--remove-unused-variables"]
+      exclude: ^.github/
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+    - id: end-of-file-fixer
+    - id: trailing-whitespace
+      exclude: ^.github/
+
+  - repo: https://github.com/pycqa/isort
+    rev: 7.0.0
+    hooks:
+      - id: isort
+        exclude: ^.github/
+
+  - repo: https://github.com/psf/black
+    rev: 25.11.0
+    hooks:
+    - id: black
+      exclude: ^.github/
+
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 1.0.0
+    hooks:
+    - id: mdformat
+      args: ["--wrap", "79"]
+      exclude: ^docs/
+      additional_dependencies:
+      - mdformat-gfm
+
+  - repo: https://github.com/djlint/djLint
+    rev: v1.36.4
+    hooks:
+      - id: djlint-reformat-jinja
+        files: \.html\.jinja$
+        types_or: [html, jinja]
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: mypy
+        language: system
+        types: [python]
+        args: ["--strict"]
+        require_serial: true
+
+      - id: pylint
+        name: pylint
+        entry: pylint
+        language: system
+        types: [python]
+
+      - id: coverage
+        name: coverage
+        entry: coverage
+        language: system
+        pass_filenames: false
+        always_run: true
+        args: [run, -m, pytest]
+
+      - id: coverage-report
+        name: coverage-report
+        entry: coverage
+        language: system
+        pass_filenames: false
+        always_run: true
+        args: [report, -m, --fail-under=100]

clindocs-1.5.1/CHANGES.md

@@ -0,0 +1,14 @@
+# Changes
+
+## v1.5.0
+
+- Name changed to clindocs
+
+## v1.4.0
+
+- Release using the clingo tree sitter for documentation parsing.
+- Docstring syntax changed, refer to the docs for details.
+
+## v0.1.0
+
+- create project

clindocs-1.5.1/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Thanks for considering a contribution to clindocs. ❤️
+
+## How to get help or discuss possible contributions
+
+To avoid duplicating issues, please search our [issue tracker][issues] and our
+[mailing list][mailing_list] before filing a new issue.
+
+- Open an [issue][new_issue] describing your problem.
+- [Subscribe] to our mailing list on SourceForge.
+
+## How to make a contribution
+
+- Fork the [clindocs][project_url] repository and create a branch for your
+  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. 🥳
+
+## License
+
+When contributing to this project, you agree that you have authored 100% of the
+content, that you have the necessary rights to the content and that the content
+you contribute may be provided under the project license.
+
+[issues]: https://github.com/potassco/clindocs.git/issues/
+[mailing_list]: https://sourceforge.net/p/potassco/mailman/potassco-users/
+[new_issue]: https://github.com/potassco/clindocs.git/issues/new/
+[project_url]: https://github.com/potassco/clindocs.git/
+[subscribe]: https://sourceforge.net/projects/potassco/lists/potassco-users/

clindocs-1.5.1/DEPLOYMENT.md

@@ -0,0 +1,15 @@
+# Deployment
+
+Releases are deployed on [pypi] whenever a tag of form `vMajor.Minor.Revision`
+is pushed. Furthermore, the deployment workflow can be triggered manually to
+deploy test releases on [test.pypi].
+
+For this to work, the workflow has to be granted permission to deploy on the
+two services. Please follow this packaging [guide] to setup your accounts
+accordingly. We also recommend to setup a github [environment] to restrict
+which contributors can deploy packages.
+
+[environment]: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment/
+[guide]: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+[pypi]: https://pypi.org/
+[test.pypi]: https://test.pypi.org/

clindocs-1.5.1/DEVELOPMENT.md

@@ -0,0 +1,62 @@
+# Development
+
+To improve code quality, we use [nox] to run linters, type checkers, unit
+tests, documentation and more. We recommend installing nox using [pipx] to have
+it available globally.
+
+```bash
+# install
+python -m pip install pipx
+python -m pipx install nox
+
+# run all sessions
+nox
+
+# list all sessions
+nox -l
+
+# run individual session
+nox -s session_name
+
+# run individual session (reuse install)
+nox -Rs session_name
+```
+
+Note that the nox sessions create [editable] installs. In case there are
+issues, try recreating environments by dropping the `-R` option. If your
+project is incompatible with editable installs, adjust the `noxfile.py` to
+disable them.
+
+We also provide a [pre-commit][pre] config to autoformat code upon commits. It
+can be set up using the following commands:
+
+```bash
+python -m pipx install pre-commit
+pre-commit install
+```
+
+## Code structure
+
+```text
+src/mkdocstrings_handlers/asp/
+└── _internal/
+    ├── collect/                        # Parsing logic (Input)
+    │   ├── queries/                    # *.scm files with tree-sitter queries
+    │   ├── extractors.py               # Extract data from nodes using queries
+    │   ├── load.py                     # File loading and processing loop
+    │   └── syntax.py                   # Query wrappers and node definitions
+    ├── render/                         # View model generation (Processing)
+    │   ├── render_context.py           # Main rendering context
+    │   ├── dependency_graph_context.py # Dependency graph context
+    │   ├── encodings_context.py        # Encodings context
+    │   ├── glossary_context.py         # Glossary context
+    │   └── predicate_table_context.py  # Predicate table context
+    ├── config.py                       # Configuration options (using Pydantic)
+    ├── domain.py                       # Domain models (Document, Statement, etc.)
+    └── handler.py                      # MkDocstrings handler entry point
+```
+
+[editable]: https://setuptools.pypa.io/en/latest/userguide/development_mode.html
+[nox]: https://nox.thea.codes/en/stable/index.html
+[pipx]: https://pypa.github.io/pipx/
+[pre]: https://pre-commit.com/

clindocs-1.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Potassco
+
+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.

clindocs-1.5.1/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: clindocs
+Version: 1.5.1
+Summary: Mkdocs plugin to generate documentation from clingo files
+Author-email: Potassco <hahnmartinlu@uni-potsdam.de>
+License: MIT License
+        
+        Copyright (c) 2024 Potassco
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/potassco/clindocs.git/
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: clingo
+Requires-Dist: mkdocstrings>=1.0.0
+Requires-Dist: tree-sitter
+Requires-Dist: tree-sitter-clingo>=1.0.5
+Requires-Dist: pydantic
+Requires-Dist: pygments_clingo
+Requires-Dist: mkdocs>=1.5
+Requires-Dist: mkdocs-material>=9.5
+Requires-Dist: mkdocs-autorefs>=1.4
+Provides-Extra: format
+Requires-Dist: black; extra == "format"
+Requires-Dist: isort; extra == "format"
+Requires-Dist: autoflake; extra == "format"
+Provides-Extra: lint-pylint
+Requires-Dist: pylint; extra == "lint-pylint"
+Requires-Dist: djlint; extra == "lint-pylint"
+Provides-Extra: typecheck
+Requires-Dist: types-setuptools; extra == "typecheck"
+Requires-Dist: mypy; extra == "typecheck"
+Requires-Dist: types-Markdown; extra == "typecheck"
+Requires-Dist: types-Pygments; extra == "typecheck"
+Provides-Extra: test
+Requires-Dist: coverage[toml]; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: doc
+Requires-Dist: mkdocstrings[python]; extra == "doc"
+Requires-Dist: mkdocs-literate-nav; extra == "doc"
+Provides-Extra: dev
+Requires-Dist: clindocs[doc,lint_pylint,test,typecheck]; extra == "dev"
+Dynamic: license-file
+
+# clindocs
+
+**clindocs** is an automated documentation tool tailored for **Answer Set
+Programming (ASP)** code. Built on [MkDocs](https://www.mkdocs.org/) and
+[mkdocs-material](https://squidfunk.github.io/mkdocs-material/), it streamlines
+the creation of high-quality documentation with the following features:
+
+- **Render encodings**: Automatically format ASP encodings with comments
+  written in Markdown.
+- **Predicate analysis**: Collect and document predicates used across included
+  files.
+- **Navigation-friendly documentation**: Generate organized predicate
+  documentation with intuitive navigation.
+- **Input/output identification**: Detect and highlight input and output
+  predicates.
+- **Dependency graphs**: Visualize dependencies between predicates and files.
+
+For installation instructions and detailed usage, visit our
+[official documentation](https://potassco.org/clindocs/docs).

clindocs-1.5.1/README.md

@@ -0,0 +1,19 @@
+# clindocs
+
+**clindocs** is an automated documentation tool tailored for **Answer Set
+Programming (ASP)** code. Built on [MkDocs](https://www.mkdocs.org/) and
+[mkdocs-material](https://squidfunk.github.io/mkdocs-material/), it streamlines
+the creation of high-quality documentation with the following features:
+
+- **Render encodings**: Automatically format ASP encodings with comments
+  written in Markdown.
+- **Predicate analysis**: Collect and document predicates used across included
+  files.
+- **Navigation-friendly documentation**: Generate organized predicate
+  documentation with intuitive navigation.
+- **Input/output identification**: Detect and highlight input and output
+  predicates.
+- **Dependency graphs**: Visualize dependencies between predicates and files.
+
+For installation instructions and detailed usage, visit our
+[official documentation](https://potassco.org/clindocs/docs).

clindocs-1.5.1/docs/SUMMARY.md

@@ -0,0 +1,25 @@
+* Getting Started
+    * [Getting Started](use/index.md)
+    * [Quick Start Guide](use/quick-start.md)
+    * [Installation](use/installation.md)
+    * [Help](use/help.md)
+* Examples
+    * [Examples](examples/index.md)
+    * [Sudoku](examples/sudoku.md)
+    * [Product Configuration](examples/config.md)
+* Reference
+    * [Reference](reference/index.md)
+    * Sections
+        * [Sections](reference/sections/index.md)
+        * [Predicate table](reference/sections/predicate-table.md)
+        * [Dependency graph](reference/sections/dependency-graph.md)
+        * [Encodings](reference/sections/encodings.md)
+        * [Glossary](reference/sections/glossary.md)
+    * [Predicate Docstring](reference/predicate-docs.md)
+    * [Style](reference/style.md)
+* Community
+    * [Community](community/index.md)
+    * [Changes](community/CHANGES.md)
+    * [Contributing](community/CONTRIBUTING.md)
+    * [Development](community/DEVELOPMENT.md)
+    * [Deployment](community/DEPLOYMENT.md)