diff --git a/.gitignore b/.gitignore index 59ddbcb..d4ac8b9 100644 --- a/.gitignore +++ b/.gitignore @@ -34,3 +34,4 @@ build .coverage _build _autosummary +site diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index dc1431c..9826ff8 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -30,6 +30,6 @@ repos: hooks: - id: mdformat args: ["--wrap", "79"] - exclude: ^doc/ + exclude: ^docs/ additional_dependencies: - mdformat-gfm diff --git a/README.md b/README.md index cdd189a..f4605e6 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ fillname -h To generate and open the documentation, run ```bash -nox -s doc -- open +nox -s doc -- serve ``` Instructions to install and use `nox` can be found in diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index d4bb2cb..0000000 --- a/doc/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css deleted file mode 100644 index b5215ee..0000000 --- a/doc/_static/css/custom.css +++ /dev/null @@ -1,33 +0,0 @@ -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; -} diff --git a/doc/_static/logo-dark-mode.png b/doc/_static/logo-dark-mode.png deleted file mode 100644 index 81ed997..0000000 Binary files a/doc/_static/logo-dark-mode.png and /dev/null differ diff --git a/doc/_static/logo-light-mode.png b/doc/_static/logo-light-mode.png deleted file mode 100644 index d2ac73d..0000000 Binary files a/doc/_static/logo-light-mode.png and /dev/null differ diff --git a/doc/conf.py b/doc/conf.py deleted file mode 100644 index a4b4e2e..0000000 --- a/doc/conf.py +++ /dev/null @@ -1,128 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -import datetime -import os -import sys -from importlib import metadata - -import toml - -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 = [] - -# -- Project information ----------------------------------------------------- - -toml_config = toml.load(os.path.join("..", "pyproject.toml")) -project = toml_config["project"]["name"] -author = ", ".join([a["name"] for a in toml_config["project"]["authors"]]) -url = toml_config["project"]["urls"]["Homepage"] -copyright = f'{datetime.datetime.now().date().strftime("%Y")}, {author}' - - -# The full version, including alpha/beta/rc tags - -release = metadata.version("fillname") - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. Make sure that custom extensions are listed in the doc field of -# [options.extras_require] in project.toml so they are available when building -# the documentation. - -extensions = [ - "furo.sphinxext", # Theme - "sphinx.ext.extlinks", - "sphinx.ext.mathjax", - "sphinx.ext.todo", - "sphinx.ext.viewcode", - "sphinx.ext.autodoc", - "sphinx.ext.napoleon", - "sphinx.ext.autosectionlabel", - "sphinx.ext.intersphinx", - "sphinx.ext.autosummary", - "sphinx_copybutton", - "myst_parser", -] - -autosummary_generate = True - -# intersphinx_mapping = {'clorm': ('https://clorm.readthedocs.io/en/latest/', None)} - -# napoleon_google_docstring = False -# napoleon_use_ivar = True -napoleon_include_init_with_doc = False -napoleon_use_admonition_for_examples = False -napoleon_use_admonition_for_references = True - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - -html_title = project - -# -- 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 = "furo" - -html_theme_options = { - # 'analytics_id': 'UA-XXXXXXX-1', # Provided by Google in your dashboard - "light_logo": "logo-light-mode.png", - "dark_logo": "logo-dark-mode.png", - "footer_icons": [ - { - "name": "GitHub", - "url": url, - "html": """ - - - - """, - "class": "", - }, - ], - # Toc options -} - - -# -- 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". -# html_static_path = ['_static'] - -copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " -copybutton_prompt_is_regexp = True diff --git a/doc/content/encodings/index.md b/doc/content/encodings/index.md deleted file mode 100644 index 2b8e2f8..0000000 --- a/doc/content/encodings/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# ASP Encodings - -Descriptions of ASP encodings. - -```{toctree} -instance.md -``` diff --git a/doc/content/encodings/instance.md b/doc/content/encodings/instance.md deleted file mode 100644 index f325dd4..0000000 --- a/doc/content/encodings/instance.md +++ /dev/null @@ -1,32 +0,0 @@ -# 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). -``` diff --git a/doc/content/installation.md b/doc/content/installation.md deleted file mode 100644 index d0a73f0..0000000 --- a/doc/content/installation.md +++ /dev/null @@ -1,41 +0,0 @@ -# Installation - -fillname requires Python 3.8+. We recommend version 3.10. - -You can check a successful installation by running - -```console -$ fillname -h -``` - -## Installing with pip - - -The python fillname package can be found [here](https://fillname.org/). - -```console -$ pip install fillname -``` - -## Development - -### Installing from source - -The project is hosted on [github](https://fillname.org/) 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: - -```console -$ git clone https://fillname.org/ -$ cd fillname -$ pip install -e .[all] -``` diff --git a/doc/content/quickstart.md b/doc/content/quickstart.md deleted file mode 100644 index 91841a9..0000000 --- a/doc/content/quickstart.md +++ /dev/null @@ -1,11 +0,0 @@ -# Quick start - -A simple explanation on how to use the system. - -```console -$ fillname -h -``` - -```{tip} -Tips on how to use the system. -``` diff --git a/doc/index.md b/doc/index.md deleted file mode 100644 index cbd580e..0000000 --- a/doc/index.md +++ /dev/null @@ -1,9 +0,0 @@ -# fillname - -An example project template. - -```{toctree} -content/installation.md -content/quickstart.md -content/encodings/index.md -``` diff --git a/docs/_custom/css/extra.css b/docs/_custom/css/extra.css new file mode 100644 index 0000000..b2264f2 --- /dev/null +++ b/docs/_custom/css/extra.css @@ -0,0 +1,30 @@ +:root { + --md-primary-fg-color: #6495ED; +} + +[data-md-color-scheme="slate"] .md-header, +[data-md-color-scheme="slate"] .md-tabs { + --md-primary-fg-color: #253758; +} + +.md-grid { + max-width: 1350px; +} + +.md-header__title { + font-size: 1.2rem; + height: 2.5rem; + line-height: 2.5rem; + margin-left: 0 !important; +} + +.md-header__button.md-logo { + /* margin-left: 30; */ + padding-bottom: 0.8rem; +} + +.md-header__button.md-logo img, +.md-header__button.md-logo svg { + height: 1.5rem; + width: 1.5rem; +} diff --git a/docs/_custom/css/mkdoclingo.css b/docs/_custom/css/mkdoclingo.css new file mode 100644 index 0000000..dce2431 --- /dev/null +++ b/docs/_custom/css/mkdoclingo.css @@ -0,0 +1,49 @@ +code.doc-clingo-symbol-encoding::after { + content: "ASP"; + color: var(--md-primary-fg-color); +} + + +code.doc-clingo-symbol-predicate::after { + content: "predicate"; + color: #ca91bf +} + + +:root { + --md-admonition-icon--asp-doc: url('data:image/svg+xml;charset=utf-8,'); + --md-admonition-icon--asp-doc-ref: url('data:image/svg+xml;charset=utf-8,') +} + +.md-typeset .admonition.asp-doc, +.md-typeset details.asp-doc { + border-color: var(--md-primary-fg-color); +} + +.md-typeset .admonition.asp-doc-ref, +.md-typeset details.asp-doc-ref { + border-color: #ca91bf; +} + +.md-typeset .asp-doc>.admonition-title, +.md-typeset .asp-doc>summary { + background-color: #1669B810; +} + +.md-typeset .asp-doc-ref>.admonition-title, +.md-typeset .asp-doc-ref>summary { + background-color: #ca91bf10; +} + +.md-typeset .asp-doc>.admonition-title::before, +.md-typeset .asp-doc>summary::before { + background-color: var(--md-primary-fg-color); + -webkit-mask-image: var(--md-admonition-icon--asp-doc); + mask-image: var(--md-admonition-icon--asp-doc); +} + +.md-typeset .asp-doc-ref>summary::before { + background-color: #ca91bf; + -webkit-mask-image: var(--md-admonition-icon--asp-doc-ref); + mask-image: var(--md-admonition-icon--asp-doc-ref); +} diff --git a/docs/_custom/css/mkdocstrings.css b/docs/_custom/css/mkdocstrings.css new file mode 100644 index 0000000..ec3f314 --- /dev/null +++ b/docs/_custom/css/mkdocstrings.css @@ -0,0 +1,50 @@ +code.doc-section-title { + font-weight: bold; +} + +code.doc-symbol-parameter::after { + content: "P"; +} + +code.doc-symbol-attribute::after { + content: "A"; +} + +code.doc-symbol-function::after { + content: "F"; +} + +code.doc-symbol-method::after { + content: "M"; +} + +code.doc-symbol-class::after { + content: "C"; +} + +code.doc-symbol-module::after { + content: "M"; +} + +:root { + --doc-symbol-parameter-fg-color: #df50af; + --doc-symbol-attribute-fg-color: #0079ff; + --doc-symbol-function-fg-color: #00dfa2; + --doc-symbol-method-fg-color: #00dfa2; + --doc-symbol-class-fg-color: #d1b619; + --doc-symbol-module-fg-color: #ff0060; + + --doc-symbol-parameter-bg-color: #df50af1a; + --doc-symbol-attribute-bg-color: #0079ff1a; + --doc-symbol-function-bg-color: #00dfa21a; + --doc-symbol-method-bg-color: #00dfa21a; + --doc-symbol-class-bg-color: #d1b6191a; + --doc-symbol-module-bg-color: #ff00601a; +} + + +.cssClass>rect { + fill: #ff0000; + stroke: #ffff00; + stroke-width: 4px; +} diff --git a/docs/_custom/javascripts/mathjax.js b/docs/_custom/javascripts/mathjax.js new file mode 100644 index 0000000..5b34852 --- /dev/null +++ b/docs/_custom/javascripts/mathjax.js @@ -0,0 +1,19 @@ +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } +}; + +document$.subscribe(() => { + MathJax.startup.output.clearCache() + MathJax.typesetClear() + MathJax.texReset() + MathJax.typesetPromise() +}) diff --git a/docs/_custom/overrides/.icons/potassco-full-logo.svg b/docs/_custom/overrides/.icons/potassco-full-logo.svg new file mode 100644 index 0000000..b5c199c --- /dev/null +++ b/docs/_custom/overrides/.icons/potassco-full-logo.svg @@ -0,0 +1,3 @@ + + + diff --git a/docs/_custom/overrides/.icons/potassco-logo.svg b/docs/_custom/overrides/.icons/potassco-logo.svg new file mode 100644 index 0000000..fde2a4a --- /dev/null +++ b/docs/_custom/overrides/.icons/potassco-logo.svg @@ -0,0 +1,3 @@ + + + diff --git a/docs/_custom/overrides/partials/logo.html b/docs/_custom/overrides/partials/logo.html new file mode 100644 index 0000000..1ea5a40 --- /dev/null +++ b/docs/_custom/overrides/partials/logo.html @@ -0,0 +1,29 @@ + + + +{% if config.theme.logo %} +logo +{% else %} +{% set icon = config.theme.icon.logo or "material/library" %} +{% include ".icons/" ~ icon ~ ".svg" %} +{% endif %} diff --git a/docs/assets/images/potassco-full-logo.svg b/docs/assets/images/potassco-full-logo.svg new file mode 100644 index 0000000..b5c199c --- /dev/null +++ b/docs/assets/images/potassco-full-logo.svg @@ -0,0 +1,3 @@ + + + diff --git a/docs/assets/images/potassco-logo-dark.svg b/docs/assets/images/potassco-logo-dark.svg new file mode 100644 index 0000000..e6706af --- /dev/null +++ b/docs/assets/images/potassco-logo-dark.svg @@ -0,0 +1,3 @@ + + + diff --git a/docs/assets/images/potassco-logo.svg b/docs/assets/images/potassco-logo.svg new file mode 100644 index 0000000..fde2a4a --- /dev/null +++ b/docs/assets/images/potassco-logo.svg @@ -0,0 +1,3 @@ + + + diff --git a/docs/community/CHANGES.md b/docs/community/CHANGES.md new file mode 120000 index 0000000..8980b4a --- /dev/null +++ b/docs/community/CHANGES.md @@ -0,0 +1 @@ +../../CHANGES.md \ No newline at end of file diff --git a/docs/community/CONTRIBUTING.md b/docs/community/CONTRIBUTING.md new file mode 120000 index 0000000..f939e75 --- /dev/null +++ b/docs/community/CONTRIBUTING.md @@ -0,0 +1 @@ +../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/community/DEPLOYMENT.md b/docs/community/DEPLOYMENT.md new file mode 120000 index 0000000..efafc4c --- /dev/null +++ b/docs/community/DEPLOYMENT.md @@ -0,0 +1 @@ +../../DEPLOYMENT.md \ No newline at end of file diff --git a/docs/community/DEVELOPMENT.md b/docs/community/DEVELOPMENT.md new file mode 120000 index 0000000..62bb95a --- /dev/null +++ b/docs/community/DEVELOPMENT.md @@ -0,0 +1 @@ +../../DEVELOPMENT.md \ No newline at end of file diff --git a/docs/community/help.md b/docs/community/help.md new file mode 100644 index 0000000..dc9121b --- /dev/null +++ b/docs/community/help.md @@ -0,0 +1,43 @@ +--- +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 new file mode 100644 index 0000000..d230d56 --- /dev/null +++ b/docs/community/index.md @@ -0,0 +1,29 @@ +# 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 new file mode 100644 index 0000000..bff9d10 --- /dev/null +++ b/docs/examples/index.md @@ -0,0 +1,23 @@ +--- +hide: + - navigation +--- + +# Examples + +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 +experienced pro, these guides will walk you through common use cases and +provide step-by-step instructions. + +## How to Use This Section + +Each example includes: + +1. **Instructions** to run the example. +1. **Code snippets** to demonstrate implementation. +1. **Helpful visuals** to illustrate key concepts. + +Dive in and start exploring! diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000..cf57665 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,35 @@ +--- +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/index.md b/docs/index.md new file mode 100644 index 0000000..2644602 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,10 @@ +--- +hide: + - navigation + - toc +--- + +# fillname + +!!! info + *fillname* is part of the [Potassco](https://potassco.org) suite. diff --git a/docs/reference/api/index.md b/docs/reference/api/index.md new file mode 100644 index 0000000..bf6914f --- /dev/null +++ b/docs/reference/api/index.md @@ -0,0 +1,12 @@ +--- +title: "API Reference" +icon: "material/book-open-variant" +--- + +# API + +::: fillname + handler: python + options: + members: true + show_submodules: true diff --git a/docs/reference/encodings/index.md b/docs/reference/encodings/index.md new file mode 100644 index 0000000..fb7f670 --- /dev/null +++ b/docs/reference/encodings/index.md @@ -0,0 +1,5 @@ +--- +icon: material/file-code +--- + +# Encodings diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 0000000..d21c7fe --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1,19 @@ +# Reference + +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. + + + +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 new file mode 100644 index 0000000..685afb9 --- /dev/null +++ b/docs/reference/problem/index.md @@ -0,0 +1,5 @@ +--- +icon: material/head-dots-horizontal +--- + +# Problem specification diff --git a/init.py b/init.py index 3e14478..8472cad 100755 --- a/init.py +++ b/init.py @@ -75,11 +75,13 @@ def replace(filepath): with open(filepath, "w", encoding="utf-8") as hnd: hnd.write(content) - dirs = [os.path.join("src", "fillname"), "tests", "doc"] + 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", diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..b6507b3 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,132 @@ +site_name: fillname +site_url: https://potassco.org/systems/fillname +site_description: +repo_name: potassco/fillname +repo_url: https://github.com/potassco/fillname +copyright: Copyright © 2024 Potassco + +extra_css: + - _custom/css/extra.css + - _custom/css/mkdocstrings.css + - _custom/css/mkdoclingo.css + +extra_javascript: + - _custom/javascripts/mathjax.js + - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js + +theme: + name: material + logo: assets/images/potassco-logo.svg + custom_dir: docs/_custom/overrides + favicon: assets/images/potassco-logo-dark.svg + features: + - header.autohide + - navigation.instant + - navigation.tracking + # - navigation.sections + - navigation.indexes + - content.code.annotate + # - toc.integrate + - toc.follow + - navigation.path + # - navigation.top + - navigation.tabs + - content.code.copy + - content.tooltips + # - navigation.instant.preview + # - navigation.expand + icon: + repo: fontawesome/brands/github + admonition: + quote: material/file-code-outline + palette: + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + 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] + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + 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 + name: Switch to light mode + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/potassco/fillname + - icon: potassco-logo + link: https://potassco.org + generator: false + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.keys + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + options: + custom_icons: + - _custom/overrides/.icons + - attr_list + - md_in_html + - pymdownx.blocks.caption + - pymdownx.snippets + - pymdownx.arithmatex: + generic: true + - toc: + permalink: true + - footnotes + +plugins: + - search + - autorefs + - mkdocstrings: + handlers: + python: + paths: [src] + import: + - https://docs.python.org/3/objects.inv + options: + show_symbol_type_heading: true + show_symbol_type_toc: true + # show_root_toc_entry: false + # show_inherited_summary: true + show_inherited_detail: true + show_inherited_detail_toc: true + show_inherited_detail_tree: true + show_signature_annotations: true + signature_crossrefs: true + show_source: false + +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/noxfile.py b/noxfile.py index e6d8125..9c64122 100644 --- a/noxfile.py +++ b/noxfile.py @@ -1,4 +1,5 @@ import os +import sys import nox @@ -17,31 +18,23 @@ def doc(session): Build the documentation. Accepts the following arguments: - - open: open documentation after build - - clean: clean up the build folder - - : build the given with the given + - serve: open documentation after build + - further arguments are passed to mkbuild """ - target = "html" - options = [] - open_doc = "open" in session.posargs - clean = "clean" in session.posargs + options = session.posargs[:] + open_doc = "serve" in options if open_doc: - session.posargs.remove("open") - if clean: - session.posargs.remove("clean") - - if session.posargs: - target = session.posargs[0] - options = session.posargs[1:] + options.remove("serve") session.install("-e", ".[doc]") - session.cd("doc") - if clean: - session.run("rm", "-rf", "_build") - session.run("sphinx-build", "-M", target, ".", "_build", *options) + if open_doc: - session.run("open", "_build/html/index.html") + open_cmd = "xdg-open" if sys.platform == "linux" else "open" + session.run(open_cmd, "http://localhost:8000/systems/fillname/") + session.run("mkdocs", "serve", *options) + else: + session.run("mkdocs", "build", *options) @nox.session diff --git a/pyproject.toml b/pyproject.toml index 17aec66..cb2a813 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 = ["sphinx", "furo", "nbsphinx", "sphinx_copybutton", "myst-parser", "toml"] +doc = ["mkdocs", "mkdocs-material", "mkdocstrings[python]"] dev = ["fillname[test,typecheck,lint_pylint]"] [project.scripts]