Merge pull request #8 from krr-up/sh/update

Sh/update

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Susana Hahn
+Copyright (c) 2024 <author>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,16 +1,18 @@
 # fillname
 
-This project template is configured to ease collaboration. Linters, formatters,
-and actions are already configured and ready to use.
-
-To use the project template, run the `init.py` script to give the project a
-name and some metadata. The script can then be removed afterward and the
-`setup.cfg` file adjusted.
+> Remove this block after following the instructions below to use the template.
+>
+> This project template is configured to ease collaboration. Linters,
+> formatters, and actions are already configured and ready to use.
+>
+> To use the project template, run the `init.py` script to give the project a
+> name and some metadata. The script can then be removed. Then adjust the
+> `setup.cfg` file as needed.
 
 ## Installation
 
 ```shell
-pip install fillname
+pip install .
 ```
 
 ## Usage
@@ -21,64 +23,41 @@ fillname -h
 
 ## Development
 
-To improve code quality, we run linters, type checkers, and unit tests. The
-tools can be run using [nox]. We recommend installing nox using [pipx] to have
-it available globally:
+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
-nox
-```
-
-You can invoke `nox -s` to run individual sessions. For example, to install
-your package into a virtual environment and run your test suite, invoke:
-
-```bash
-nox -s test
-```
 
-We also provide a nox session that creates an environment for development. The
-project is installed in [editable] mode into this environment along with
-linting, type checking and formatting tools. Activating it allows your editor
-of choice to access these tools for, e.g., linting and autocompletion. To
-create and then activate virtual environment run:
+# run all sessions
+nox
 
-```bash
-nox -s dev
-source .nox/dev/bin/activate
-```
+# list all sessions
+nox -l
 
-Furthermore, we provide individual sessions to easily run linting, type
-checking and formatting via nox. These also create editable installs. So you
-can safely skip the recreation of the virtual environment and reinstallation of
-your package in subsequent runs by passing the `-R` command line argument. For
-example, to auto-format your code using [black], run:
+# run individual session
+nox -s session_name
 
-```bash
-nox -Rs format -- check
-nox -Rs format
+# run individual session (reuse install)
+nox -Rs session_name
 ```
 
-The former command allows you to inspect changes before applying them.
-
-Note that editable installs have some caveats. In case there are issues, try
-recreating environments by dropping the `-R` option. If your project is
+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 automate this process. It can be
-set up using the following commands:
+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
 ```
 
-This blackens the source code whenever `git commit` is used.
-
-[doc]: https://potassco.org/clingo/python-api/current/
 [nox]: https://nox.thea.codes/en/stable/index.html
 [pipx]: https://pypa.github.io/pipx/
 [pre]: https://pre-commit.com/
-[black]: https://black.readthedocs.io/en/stable/
 [editable]: https://setuptools.pypa.io/en/latest/userguide/development_mode.html

doc/_static/css/custom.css

@@ -0,0 +1,33 @@
+div.admonition.example {
+  border-color: hsl(257, 20%, 50%);
+  background-color: hsl(257, 20%, 80%);
+}
+
+div.admonition.example > .admonition-title {
+  color: white;
+  background-color: hsl(257, 20%, 50%);
+}
+
+div.admonition.example > .admonition-title::before {
+  content: "\f2a7";
+}
+
+.sidebar-logo {
+  margin: inherit;
+}
+.sidebar-logo-container{
+  max-width: 20%!important;
+  margin-top: 0.2rem;
+  margin-right: 0.2rem;
+  justify-content: flex-end;
+  display: flex;
+}
+.sidebar-brand-text {
+  text-align: center !important;
+  align-items: center;
+  display: inline-flex;
+}
+
+.sidebar-brand {
+  flex-direction: row !important;
+}

doc/conf.py

@@ -9,7 +9,9 @@
 import configparser
 import datetime
 import os
+import sys
 
+sys.path.insert(0, os.path.abspath("."))
 # modules that autodock should mock
 # useful if some external dependencies are not satisfied at doc build time.
 autodoc_mock_imports = []
@@ -36,13 +38,18 @@
 # the documentation.
 
 extensions = [
-    "nbsphinx",
-    "sphinx_rtd_theme",
+    "furo.sphinxext",  # Theme
+    "sphinx.ext.extlinks",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
     "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.autosummary",
+    "sphinx_copybutton",
+    "myst_parser",
 ]
 
 autosummary_generate = True
@@ -63,31 +70,53 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+html_title = _meta["name"]
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "furo"
 
 html_theme_options = {
-    "canonical_url": "",
     #    'analytics_id': 'UA-XXXXXXX-1',  #  Provided by Google in your dashboard
-    "logo_only": False,
-    "display_version": True,
-    "display_version": True,
-    "prev_next_buttons_location": "bottom",
-    "style_external_links": False,
+    "light_logo": "logo-light-mode.png",
+    "dark_logo": "logo-dark-mode.png",
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": _meta["url"],
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ]
     # Toc options
-    "collapse_navigation": True,
-    "sticky_navigation": False,
-    "navigation_depth": 4,
-    "includehidden": True,
-    "titles_only": False,
 }
 
 
+# -- Options for Markdown files ----------------------------------------------
+#
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+]
+myst_heading_anchors = 3
+
+# -- Custom css
+html_css_files = [
+    "css/custom.css",
+]
+
+html_static_path = ["_static"]
+
+add_module_names = False  # Class names without full module path
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".

doc/content/encodings/index.md

@@ -0,0 +1,7 @@
+# ASP Encodings
+
+Descriptions of ASP encodings.
+
+```{toctree}
+instance.md
+```

doc/content/encodings/instance.md

@@ -0,0 +1,32 @@
+# Instance
+
+## Constants
+```{list-table}
+:header-rows: 1
+:widths: 25 100
+
+* - Name
+  - Description
+* - `horizon`
+  - The description of a constant.
+```
+
+## Predicates
+
+### `predicate(X,Y)`
+
+Description
+
+```{admonition} Example
+```prolog
+predicate(1,2).
+```
+
+### `another_predicate(X)`
+
+Description
+
+```{admonition} Example
+```prolog
+another_predicate(1).
+```

doc/content/installation.md

@@ -0,0 +1,41 @@
+# Installation
+
+fillname requires Python 3.8+. We recommend version 3.10.
+
+You can check a successful installation by running
+
+```shell
+fillname -h
+```
+
+## Installing with pip
+
+
+The python fillname package can be found [here](https://pypi.org/project/fillname/).
+
+```shell
+pip install fillname
+```
+
+## Development
+
+### Installing from source
+
+The project is hosted on [github](https://github.com/potassco/fillname) and can
+also be installed from source.
+
+```{warning}
+We recommend this only for development purposes.
+```
+
+```{note}
+The `setuptools` package is required to run the commands below.
+```
+
+Execute the following command in the top level fillname directory:
+
+```shell
+git clone https://github.com/potassco/fillname
+cd fillname
+pip install -e .[all]
+```

doc/content/quickstart.md

@@ -0,0 +1,11 @@
+# Quick start
+
+A simple explanation on how to use the system.
+
+```shell
+fillname -h
+```
+
+```{tip}
+Tips on how to use the system.
+```

doc/index.md

@@ -0,0 +1,9 @@
+# fillname
+
+An example project template.
+
+```{toctree}
+content/installation.md
+content/quickstart.md
+content/encodings/index.md
+```

init.py

@@ -43,22 +43,25 @@ def replace(filepath):
         with open(filepath, "w", encoding="utf-8") as hnd:
             hnd.write(content)
 
-    for rootpath in [os.path.join("src", "fillname"), "tests"]:
+    dirs = [os.path.join("src", "fillname"), "tests", "doc"]
+    files = [
+        "setup.cfg",
+        "noxfile.py",
+        "README.md",
+        "LICENSE",
+        ".pre-commit-config.yaml",
+        ".coveragerc",
+    ]
+
+    for rootpath in dirs:
         for dirpath, _, filenames in os.walk(rootpath):
             for filename in filenames:
-                if not filename.endswith(".py"):
+                if not filename.endswith(".py") and not filename.endswith(".md"):
                     continue
                 filepath = os.path.join(dirpath, filename)
                 replace(filepath)
 
-    for filepath in [
-        "setup.cfg",
-        "noxfile.py",
-        "README.md",
-        "doc/index.rst",
-        ".pre-commit-config.yaml",
-        ".coveragerc",
-    ]:
+    for filepath in files:
         replace(filepath)
 
     os.rename(os.path.join("src", "fillname"), os.path.join("src", project))