Restore docs with mkdocs

.pre-commit-config.yaml

@@ -34,13 +34,3 @@ repos:
       - id: poetry-lock
         name: poetry lock
         args: [ "--no-update" ]
-      # INSTRUCTION: Remove these hooks if you wish not to produce requirement files
-      - id: poetry-export
-        name: poetry export (requirements.txt)
-        args: [ "-f", "requirements.txt", "-o", "requirements.txt" ]
-      - id: poetry-export
-        name: poetry export (dev-requirements.txt)
-        args: [ "--with", "dev", "-f", "requirements.txt", "-o", "dev-requirements.txt" ]
-      - id: poetry-export
-        name: poetry export (docs/requirements.txt)
-        args: [ "--with", "docs", "-f", "requirements.txt", "-o", "docs/requirements.txt" ]

Justfile

@@ -28,12 +28,12 @@ format:
     ruff check --fix && ruff format
 
 # Check code with ruff
-ruff:
-    ruff check
+ruff +ARGS='check':
+    ruff {{ARGS}}
 
 # Type checking on all Python source files
-pyright:
-    pyright
+pyright +ARGS='':
+    pyright {{ARGS}}
 
 # Run pytest against source files
 pytest +ARGS='-v':
@@ -58,13 +58,13 @@ cleantest:
 # |___/\___/\__\__, \___|_||_|
 #              |___/
 
-# Generate documentation though BUILDER
-docs BUILDER='help':
-    poetry run sphinx-build -M {{BUILDER}} docs docs/_build
+# Generate static-site documentation using mkdocs
+docs:
+    mkdocs build
 
-# Generate live HTML view of documentation
-autodocs:
-    poetry run sphinx-autobuild -b html docs docs/_build/livehtml
+# Live preview of documentation site
+docs-dev:
+    mkdocs serve
 
 #  ___ _            _           _
 # / __| |_  ___ _ _| |_ __ _  _| |_ ___

docs/api/app.md

@@ -0,0 +1,7 @@
+# Public Application Functions
+
+Here is the complete list of public functions.
+
+::: myhelpers.dummy.longest_common_prefix
+    options:
+      show_root_heading: true

docs/api/helpers.md

@@ -0,0 +1,6 @@
+# Additional Primitive Helpers
+
+Here is a list of additional primitive helpers.
+
+::: myhelpers.primitives.envvar.EnvVariable
+::: myhelpers.primitives.singleton.SingletonMeta

docs/api/index.md

@@ -0,0 +1,8 @@
+---
+icon: material/code-tags
+---
+
+# API Reference
+
+This section contains public API References to source code.
+Refer to each subpage for more content.

docs/index.md

@@ -0,0 +1,14 @@
+---
+title: Home
+description: Welcome to the documentation of your code
+icon: material/home
+---
+
+# Documentation
+
+This is the main page of the documentation to your code.
+Feel free to write article or customize all you want.
+
+## Useful Links
+
+- [API Reference](API%20Reference/index.md)

docs/javascripts/katex.js

@@ -0,0 +1,10 @@
+document$.subscribe(({ body }) => {
+  renderMathInElement(body, {
+    delimiters: [
+      { left: "$$",  right: "$$",  display: true },
+      { left: "$",   right: "$",   display: false },
+      { left: "\\(", right: "\\)", display: false },
+      { left: "\\[", right: "\\]", display: true }
+    ],
+  })
+})

mkdocs.yml

@@ -0,0 +1,77 @@
+# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+site_name: "My Project"
+site_url: "https://example.com/"
+repo_url: https://github.com/abhabongse/python-project
+nav:
+  - Home: index.md
+  - "API Reference":
+    - ./api/index.md
+    - "App Functions": ./api/app.md
+    - "Helper Functions": ./api/helpers.md
+theme:
+  # More info: https://squidfunk.github.io/mkdocs-material/creating-your-site/
+  name: material
+  palette:
+    scheme: slate
+    primary: black
+    accent: orange
+  font:
+    text: "IBM Plex Sans"
+    code: "JetBrains Mono"
+  icon:
+    annotation: material/plus-circle-outline
+  features:
+    - content.code.copy
+    - content.code.select
+    - content.tooltips
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.path
+    - navigation.indexes
+    - search.suggest
+    - search.highlight
+# noinspection YAMLSchemaValidation
+plugins:
+  - glightbox
+  - mkdocstrings:
+      enabled: true
+      default_handler: python
+      handlers:
+        python:
+          options:
+            show_root_heading: true
+            heading_level: 3
+          import:
+            - https://docs.python.org/3/objects.inv
+  - search
+  - social
+# noinspection YAMLSchemaValidation
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.details
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - tables
+  - toc:
+      title: On this page
+      permalink: true
+extra_javascript:
+  - ./javascripts/katex.js
+  - https://cdn.jsdelivr.net/npm/katex@0.16/dist/katex.min.js
+  - https://cdn.jsdelivr.net/npm/katex@0.16/dist/contrib/auto-render.min.js
+extra_css:
+  - https://cdn.jsdelivr.net/npm/katex@0.16/dist/katex.min.css