datafun-toolkit/zensical.toml at main · denisecase/datafun-toolkit · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
# ============================================================
# zensical.toml (Zensical configuration file)
# ============================================================

# WHY: Centralizes project documentation configuration.
# Zensical is a drop-in replacement for MkDocs that provides AI-assisted docstring generation and enhanced documentation features.
# It is used in this project to streamline documentation and provide better support for docstring generation.

[project]
site_name = "DataFun Toolkit"
site_url = "https://denisecase.github.io/datafun-toolkit/"
repo_url = "https://github.com/denisecase/datafun-toolkit"
repo_name = "denisecase/datafun-toolkit"
site_description = "Opinionated guide to professional Python projects"
docs_dir = "docs" # source directory for documentation markdown files
site_dir = "site" # output directory for generated site (ignored by Git; not in repo)
edit_uri = "edit/main/docs/" # "Edit this page" links (GitHub)

[project.extra]
# WHY: Social links provide easy access to project repositories and profiles.
social = [
    { icon = "fontawesome/brands/github", link = "https://github.com/denisecase/datafun-toolkit" },
]

# ------------------------------------------------------------
# Plugins
# ------------------------------------------------------------
[project.plugins.search]
lang = "en" # WHY: Search plugin provides instant search functionality for documentation.

[project.plugins.mkdocstrings.handlers.python]
paths = ["src"] # WHY: MkDocstrings auto-generates documentation from code; this points it to the source code directory.

[project.plugins.mkdocstrings.handlers.python.options]
docstring_style = "google" # WHY: Google style docstrings are widely used and supported by many tools, including Zensical's AI-assisted generation.
show_source = true # WHY: Showing source code in documentation can help users understand implementation details.
show_root_heading = true
show_root_toc_entry = true
show_signature_annotations = true
separate_signature = true

[project.theme]
# SEE: https://zensical.org/docs/setup/navigation/#instant-navigation-zensicaltoml
features = [
    "navigation.tracking", # WHY: Tracking allows for analytics on how users interact with the documentation, which can inform improvements.
    "navigation.expand", # WHY: Expandable navigation allows users to focus on relevant sections while keeping the overall structure accessible.
    "navigation.path", # WHY: Path navigation helps users understand their location within the documentation hierarchy.
    "navigation.prune", # WHY: Pruning simplifies navigation by hiding irrelevant sections based on the current page.
    "navigation.indexes", # WHY: Indexes provide an overview of the documentation structure and allow for quick access to different sections.
    "toc.follow", # WHY: Following the table of contents enhances user experience by keeping the navigation in sync with the current page.
    "toc.integrate", # WHY: Integrating the table of contents into the navigation provides a more cohesive and user-friendly interface.
    "navigation.top",# WHY: A "Back to top" button improves usability by allowing users to quickly return to the top of the page.
 ]

# ------------------------------------------------------------
# Navigation
# ------------------------------------------------------------
# Zensical supports navigation configuration; the shape below mirrors your MkDocs nav.
# If you later decide to rely more on folder-based navigation, you can simplify.

nav = [
  { title = "Start", path = "index.md" },
  { title = "Home", path = "en/index.md" },
  { title = "API", path = "en/api.md" },
  { title = "Examples", path = "en/examples.md" },
  { title = "Troubleshooting", path = "en/troubleshooting.md" },
]