From 3c6019516d07b0c3c89e814477a64facf164d463 Mon Sep 17 00:00:00 2001 From: Susana Hahn Date: Wed, 11 Dec 2024 17:25:58 -0600 Subject: [PATCH 1/4] More evolved template --- docs/_custom/css/extra.css | 2 +- docs/community/index.md | 5 + docs/examples/index.md | 2 +- docs/examples/sudoku/index.md | 21 ++++ docs/installation.md | 24 ++++ docs/reference/index.md | 5 + docs/usage.md | 13 ++ examples/sudoku/encoding.lp | 15 +++ examples/sudoku/instance.lp | 35 ++++++ mkdocs.yml | 31 +++-- .../material/example_template.html.jinja | 112 ++++++++++++++++++ 11 files changed, 250 insertions(+), 15 deletions(-) create mode 100644 docs/examples/sudoku/index.md create mode 100644 docs/installation.md create mode 100644 docs/usage.md create mode 100644 examples/sudoku/encoding.lp create mode 100644 examples/sudoku/instance.lp create mode 100644 src/mkdocstrings_handlers/asp/templates/material/example_template.html.jinja diff --git a/docs/_custom/css/extra.css b/docs/_custom/css/extra.css index b2264f2..c6d10cf 100644 --- a/docs/_custom/css/extra.css +++ b/docs/_custom/css/extra.css @@ -1,5 +1,5 @@ :root { - --md-primary-fg-color: #6495ED; + --md-primary-fg-color: #4378dc; } [data-md-color-scheme="slate"] .md-header, diff --git a/docs/community/index.md b/docs/community/index.md index 47281f9..98b8d85 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -1,3 +1,8 @@ +--- +hide: + - toc +--- + # Community Welcome to the **Community** hub! 🚀 diff --git a/docs/examples/index.md b/docs/examples/index.md index bff9d10..07cd51d 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -1,6 +1,6 @@ --- hide: - - navigation + - toc --- # Examples diff --git a/docs/examples/sudoku/index.md b/docs/examples/sudoku/index.md new file mode 100644 index 0000000..daf7ffd --- /dev/null +++ b/docs/examples/sudoku/index.md @@ -0,0 +1,21 @@ +# Sudoku + +Generate example documentation + + + +=== "Usage :material-file-code-outline:" + + ``` markdown title="Simple encoding source" + ::: examples/sudoku/encoding.lp + handler: asp + ``` + + !!! warning "Don't forget to use `handler: asp`" + +=== "Output :material-palette-outline:" + + + ::: examples/sudoku/encoding.lp + handler: asp + diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..f591556 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,24 @@ +--- +icon: "material/wrench" +--- + +# Getting started + +## Installation + +### Using `pip` + +```console +pip install mkdoclingo +``` + +### Development mode + +```console +git clone https://github.com/potassco/mkdoclingo.git/ +cd mkdoclingo +pip install -e .[all] +``` + +!!! warning + Use only for development purposes diff --git a/docs/reference/index.md b/docs/reference/index.md index d21c7fe..e89421d 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,3 +1,8 @@ +--- +hide: + - toc +--- + # Reference Welcome to the **Reference** section! 📚 diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..1778deb --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,13 @@ +--- +icon: "material/rocket-launch" +--- + +# Usage + +## Command line interface + +Details about the command line usage can be found with: + +```console +mkdoclingo -h +``` diff --git a/examples/sudoku/encoding.lp b/examples/sudoku/encoding.lp new file mode 100644 index 0000000..c8c9ba1 --- /dev/null +++ b/examples/sudoku/encoding.lp @@ -0,0 +1,15 @@ +#const dim = 3. +val(1..dim*dim). +pos(X,Y) :- val(X), val(Y). + +subgrid(X,Y,(((X-1)/dim)*dim+((Y-1)/dim))) :- pos(X,Y). + + +1 { sudoku(X,Y,V) : val(V) } 1 :- pos(X,Y). + +:- sudoku(X,Y,V), sudoku(X',Y,V), X != X'. +:- sudoku(X,Y,V), sudoku(X,Y',V), Y != Y'. +:- sudoku(X,Y,V), sudoku(X',Y',V), subgrid(X,Y,S), subgrid(X',Y',S), (X,Y)!=(X',Y'). + + +sudoku(X,Y,V) :- initial(X,Y,V). diff --git a/examples/sudoku/instance.lp b/examples/sudoku/instance.lp new file mode 100644 index 0000000..96db3c1 --- /dev/null +++ b/examples/sudoku/instance.lp @@ -0,0 +1,35 @@ +initial(5,1,8). +initial(6,2,7). +initial(7,1,4). +initial(8,2,2). +initial(8,1,6). +initial(9,2,9). +initial(3,3,9). +initial(4,3,3). +initial(6,3,6). +initial(7,3,5). +initial(8,3,7). +initial(1,4,7). +initial(2,4,6). +initial(4,4,4). +initial(7,4,9). +initial(8,4,3). +initial(2,5,3). +initial(3,5,2). +initial(4,5,8). +initial(7,5,7). +initial(9,5,5). +initial(1,6,9). +initial(2,6,1). +initial(3,6,8). +initial(8,6,4). +initial(9,6,6). +initial(1,7,6). +initial(5,7,7). +initial(6,7,8). +initial(8,7,9). +initial(9,7,4). +initial(2,8,7). +initial(3,8,3). +initial(4,8,6). +initial(5,8,9). diff --git a/mkdocs.yml b/mkdocs.yml index 03d0d27..037a28d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -115,18 +115,23 @@ plugins: show_source: false nav: - - Home: index.md - - Getting Started: getting_started.md - - Examples: examples/index.md + # - Home: index.md + - Getting Started: + - Installation: installation.md + - Usage: usage.md + - Examples: + - examples/index.md + - Sudoku: + - examples/sudoku/index.md - Reference: - - reference/index.md - - Problem: reference/problem/index.md - - Encodings: reference/encodings/index.md - - API: reference/api/index.md + - 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 + - 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/src/mkdocstrings_handlers/asp/templates/material/example_template.html.jinja b/src/mkdocstrings_handlers/asp/templates/material/example_template.html.jinja new file mode 100644 index 0000000..85a9f97 --- /dev/null +++ b/src/mkdocstrings_handlers/asp/templates/material/example_template.html.jinja @@ -0,0 +1,112 @@ + +

{{path}}

+ + + + + + + + + + {% for x in predicates if x.type == 'defined' %} + + + + + + {% endfor %} + {% for x in predicates if x.type == 'auxiliary' %} + + + + + + {% endfor %} + {% for x in predicates if x.type == 'shown' %} + + + + + + {% endfor %} + + +
PredicateDescriptionType
{{ x.name }}/{{x.arity}}{{ x.description }} + + + + + + + +
{{ x.name }}/{{x.arity}}{{ x.description }} + +
{{ x.name }}/{{x.arity}}{{ x.description }} + +
+ +``` mermaid +flowchart LR + {% for x in predicates %} + {{x.name}}/{{x.arity}}(["{{x.name}}/{{x.arity}}"]) + {% endfor %} + classDef all fill:#00000000 + classDef in stroke:#9178C6,stroke-width:3px; + classDef out stroke:#52BF54,stroke-width:3px; + classDef aux stroke:#848484,stroke-width:0.2px; + class {% for x in predicates %}{{x.name}}/{{x.arity}},{% endfor %} all; + class {% for x in predicates%}{%if x.type== 'defined'%}{{x.name}}/{{x.arity}},{% endif %}{% endfor %} in; + class {% for x in predicates%}{%if x.type== 'shown'%}{{x.name}}/{{x.arity}},{% endif %}{% endfor %} out; + class {% for x in predicates%}{%if x.type== 'auxiliary'%}{{x.name}}/{{x.arity}},{% endif %}{% endfor %} aux; +``` + +
+Source code +
+```prolog +{{content}} +``` +
+
+ +
+

ASP Encoding (expanded)

+

+```prolog +{{content}} +``` +

+
+ +## Glossary + +{% for x in predicates %} +#### `{{x.name}}/{{x.arity}}` + +{{x.description}} + + + + + + + + + + + + {% for p in x.parameters %} + + + + + + {% endfor %} + +
ParameterDescriptionType
{{ p.name }}{{ p.description }}{{ p.type }}
+ +
+{% endfor %} + + From 711ffae0a1b05d46e70685b90ad0ad2344e697dc Mon Sep 17 00:00:00 2001 From: Susana Hahn Date: Mon, 16 Dec 2024 09:00:14 -0600 Subject: [PATCH 2/4] General doc settings --- docs/_custom/css/extra.css | 10 +- docs/getting_started.md | 35 ------ init.py | 107 ------------------ mkdocs.yml | 4 +- .../templates/material/example_template.html | 7 -- 5 files changed, 9 insertions(+), 154 deletions(-) delete mode 100644 docs/getting_started.md delete mode 100755 init.py delete mode 100644 src/mkdocstrings_handlers/asp/templates/material/example_template.html diff --git a/docs/_custom/css/extra.css b/docs/_custom/css/extra.css index c6d10cf..034a495 100644 --- a/docs/_custom/css/extra.css +++ b/docs/_custom/css/extra.css @@ -1,12 +1,16 @@ -:root { +[data-md-color-scheme="default"] { --md-primary-fg-color: #4378dc; + --md-primary-fg-color--light: #4378dc; + --md-primary-fg-color--dark: #4378dc; } -[data-md-color-scheme="slate"] .md-header, -[data-md-color-scheme="slate"] .md-tabs { +[data-md-color-scheme="slate"] { + --md-typeset-a-color: #4378dc; --md-primary-fg-color: #253758; + --md-primary-fg-color--dark: #253758; } + .md-grid { max-width: 1350px; } diff --git a/docs/getting_started.md b/docs/getting_started.md deleted file mode 100644 index 8fc0838..0000000 --- a/docs/getting_started.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -hide: - - navigation ---- - -# Getting started - -## Installation - -=== "Pip" - -```console -pip install mkdoclingo -``` - -=== "Development mode" - -```console -git clone https://github.com/potassco/mkdoclingo.git/ -cd mkdoclingo -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 -mkdoclingo -h -``` diff --git a/init.py b/init.py deleted file mode 100755 index 8472cad..0000000 --- a/init.py +++ /dev/null @@ -1,107 +0,0 @@ -#!/usr/bin/env python3 -""" -Init script to rename project. -""" - -import os -import re -import subprocess - - -def read(prompt, regex, default): - """ - Read a string from command line. - - The string has to match the given regular expression. - """ - if default: - prompt += f" [{default}]" - prompt += ": " - - while True: - ret = input(prompt) - if not ret and default: - ret = default - match = re.match(regex, ret) - if match is not None: - return ret - print(f"the project name has to match the regular expression: {regex}") - - -def git_config_get(attr): - """ - Get a git config value. - """ - try: - return subprocess.check_output(["git", "config", "--get", attr]).decode().strip() - except subprocess.CalledProcessError: - return None - - -def main(): - """ - Rename the project. - """ - - author = git_config_get("user.name") - email = git_config_get("user.email") - origin = git_config_get("remote.origin.url") - url, project = None, None - - if origin is not None: - match = re.match(r"^.*[:/]([^:/]*)/([^/]*)(\.git)?$", origin) - if match is not None: - org, project = match.group(1), match.group(2) - url = f"https://github.com/{org}/{project}/" - project = project.replace("-", "_") - - project = read("project name", r"^[a-z][a-z0-9_]*$", project) - author = read("author", r".+", author) - email = read("email", r".+", email) - url = read("url", r".+", url) - - replacements = { - "author@fillname.org": email, - "Author Fillname": author, - "https://fillname.org/": url, - "fillname": project, - } - - def replace(filepath): - with open(filepath, "r", encoding="utf-8") as hnd: - content = hnd.read() - for key, val in replacements.items(): - content = content.replace(key, val) - with open(filepath, "w", encoding="utf-8") as hnd: - hnd.write(content) - - dirs = [os.path.join("src", "fillname"), "tests", "docs"] - files = [ - ".pre-commit-config.yaml", - "mkdocs.yml", - "noxfile.py", - "pyproject.toml", - "CHANGES.md", - "CONTRIBUTING.md", - "DEPLOYMENT.md", - "DEVELOPMENT.md", - "LICENSE", - "README.md", - ] - - for rootpath in dirs: - for dirpath, _, filenames in os.walk(rootpath): - for filename in filenames: - if not filename.endswith(".py") and not filename.endswith(".md"): - continue - filepath = os.path.join(dirpath, filename) - replace(filepath) - - for filepath in files: - replace(filepath) - - os.rename(os.path.join("src", "fillname"), os.path.join("src", project)) - - -if __name__ == "__main__": - main() diff --git a/mkdocs.yml b/mkdocs.yml index 037a28d..27afc13 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,7 +44,7 @@ theme: - media: "(prefers-color-scheme: light)" scheme: default toggle: - icon: material/brightness-7 + icon: material/weather-night name: Switch to dark mode primary: custom #, [red, pink, purple, deep, purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange, brown, grey, blue, grey, black, white] accent: indigo # [red, pink, purple, deep, purple, indigo, blue, light, blue, cyan, teal, green, light, green, lime, yellow, amber, orange, deep orange] @@ -55,7 +55,7 @@ theme: primary: custom #, [red, pink, purple, deep, purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange, brown, grey, blue, grey, black, white] accent: indigo # [red, pink, purple, deep, purple, indigo, blue, light, blue, cyan, teal, green, light, green, lime, yellow, amber, orange, deep orange] toggle: - icon: material/brightness-4 + icon: material/weather-sunny name: Switch to light mode extra: diff --git a/src/mkdocstrings_handlers/asp/templates/material/example_template.html b/src/mkdocstrings_handlers/asp/templates/material/example_template.html deleted file mode 100644 index 8e05089..0000000 --- a/src/mkdocstrings_handlers/asp/templates/material/example_template.html +++ /dev/null @@ -1,7 +0,0 @@ -!!! info - This is an example template for basic encoding documentation. - For lack of better knowledge, this template uses markdown syntax. - -```asp -{{content}} -``` From 19a182af1b99905af1e2b3ed2a530e2b700cee67 Mon Sep 17 00:00:00 2001 From: Susana Hahn Date: Mon, 16 Dec 2024 11:20:01 -0600 Subject: [PATCH 3/4] Rebased and added dependency --- docs/community/CHANGES.md | 2 +- docs/community/CONTRIBUTING.md | 2 +- docs/community/DEPLOYMENT.md | 2 +- docs/community/DEVELOPMENT.md | 2 +- docs/examples/{sudoku/index.md => sudoku.md} | 7 ++++++- mkdocs.yml | 3 +-- pyproject.toml | 2 +- 7 files changed, 12 insertions(+), 8 deletions(-) rename docs/examples/{sudoku/index.md => sudoku.md} (75%) diff --git a/docs/community/CHANGES.md b/docs/community/CHANGES.md index 0d15de6..8980b4a 120000 --- a/docs/community/CHANGES.md +++ b/docs/community/CHANGES.md @@ -1 +1 @@ -../../CHANGES.md +../../CHANGES.md \ No newline at end of file diff --git a/docs/community/CONTRIBUTING.md b/docs/community/CONTRIBUTING.md index bcac999..f939e75 120000 --- a/docs/community/CONTRIBUTING.md +++ b/docs/community/CONTRIBUTING.md @@ -1 +1 @@ -../../CONTRIBUTING.md +../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/community/DEPLOYMENT.md b/docs/community/DEPLOYMENT.md index e2669b0..efafc4c 120000 --- a/docs/community/DEPLOYMENT.md +++ b/docs/community/DEPLOYMENT.md @@ -1 +1 @@ -../../DEPLOYMENT.md +../../DEPLOYMENT.md \ No newline at end of file diff --git a/docs/community/DEVELOPMENT.md b/docs/community/DEVELOPMENT.md index eb08fc1..62bb95a 120000 --- a/docs/community/DEVELOPMENT.md +++ b/docs/community/DEVELOPMENT.md @@ -1 +1 @@ -../../DEVELOPMENT.md +../../DEVELOPMENT.md \ No newline at end of file diff --git a/docs/examples/sudoku/index.md b/docs/examples/sudoku.md similarity index 75% rename from docs/examples/sudoku/index.md rename to docs/examples/sudoku.md index daf7ffd..7632e1a 100644 --- a/docs/examples/sudoku/index.md +++ b/docs/examples/sudoku.md @@ -9,6 +9,9 @@ Generate example documentation ``` markdown title="Simple encoding source" ::: examples/sudoku/encoding.lp handler: asp + options: + source: true + ``` !!! warning "Don't forget to use `handler: asp`" @@ -18,4 +21,6 @@ Generate example documentation ::: examples/sudoku/encoding.lp handler: asp - + options: + source: true + dependency: true diff --git a/mkdocs.yml b/mkdocs.yml index 27afc13..93b12a3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -121,8 +121,7 @@ nav: - Usage: usage.md - Examples: - examples/index.md - - Sudoku: - - examples/sudoku/index.md + - examples/sudoku.md - Reference: - reference/index.md - Problem: reference/problem/index.md diff --git a/pyproject.toml b/pyproject.toml index 24032f4..d6b3f4f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,7 +19,7 @@ format = ["black", "isort", "autoflake"] lint_pylint = ["pylint"] typecheck = ["types-setuptools", "mypy"] test = ["coverage[toml]"] -doc = ["mkdocs", "mkdocs-material", "mkdocstrings[python]"] +doc = ["mkdocs", "mkdocs-material", "mkdocstrings[python]", "tree-sitter"] dev = ["mkdoclingo[test,typecheck,lint_pylint]"] [project.scripts] From 179de2b8ee28b6c840e68836840ca6910057dbba Mon Sep 17 00:00:00 2001 From: Susana Hahn Date: Mon, 16 Dec 2024 11:51:01 -0600 Subject: [PATCH 4/4] Removed template not needed --- .../material/example_template.html.jinja | 112 ------------------ 1 file changed, 112 deletions(-) delete mode 100644 src/mkdocstrings_handlers/asp/templates/material/example_template.html.jinja diff --git a/src/mkdocstrings_handlers/asp/templates/material/example_template.html.jinja b/src/mkdocstrings_handlers/asp/templates/material/example_template.html.jinja deleted file mode 100644 index 85a9f97..0000000 --- a/src/mkdocstrings_handlers/asp/templates/material/example_template.html.jinja +++ /dev/null @@ -1,112 +0,0 @@ - -

{{path}}

- - - - - - - - - - {% for x in predicates if x.type == 'defined' %} - - - - - - {% endfor %} - {% for x in predicates if x.type == 'auxiliary' %} - - - - - - {% endfor %} - {% for x in predicates if x.type == 'shown' %} - - - - - - {% endfor %} - - -
PredicateDescriptionType
{{ x.name }}/{{x.arity}}{{ x.description }} - - - - - - - -
{{ x.name }}/{{x.arity}}{{ x.description }} - -
{{ x.name }}/{{x.arity}}{{ x.description }} - -
- -``` mermaid -flowchart LR - {% for x in predicates %} - {{x.name}}/{{x.arity}}(["{{x.name}}/{{x.arity}}"]) - {% endfor %} - classDef all fill:#00000000 - classDef in stroke:#9178C6,stroke-width:3px; - classDef out stroke:#52BF54,stroke-width:3px; - classDef aux stroke:#848484,stroke-width:0.2px; - class {% for x in predicates %}{{x.name}}/{{x.arity}},{% endfor %} all; - class {% for x in predicates%}{%if x.type== 'defined'%}{{x.name}}/{{x.arity}},{% endif %}{% endfor %} in; - class {% for x in predicates%}{%if x.type== 'shown'%}{{x.name}}/{{x.arity}},{% endif %}{% endfor %} out; - class {% for x in predicates%}{%if x.type== 'auxiliary'%}{{x.name}}/{{x.arity}},{% endif %}{% endfor %} aux; -``` - -
-Source code -
-```prolog -{{content}} -``` -
-
- -
-

ASP Encoding (expanded)

-

-```prolog -{{content}} -``` -

-
- -## Glossary - -{% for x in predicates %} -#### `{{x.name}}/{{x.arity}}` - -{{x.description}} - - - - - - - - - - - - {% for p in x.parameters %} - - - - - - {% endfor %} - -
ParameterDescriptionType
{{ p.name }}{{ p.description }}{{ p.type }}
- -
-{% endfor %} - -