Sphinx docs gh-pages implementation (#453)

- using the Sphinx docs framework. 
- restructured docs into directories to create some high level organisation.
- initialised as a zk notebook for quick editing and zk specific workflow enhancements.
- docs development, local build steps and requirements to be documented in subsequent PR.

Author: tjex

.gitignore

@@ -20,5 +20,30 @@
 # IDEs/Editors
 .vscode/
 
+# Zk specific
 notebook.db
 zk
+
+# Sphinx Docs / Python #
+# created by `make docs` for building documentation locally
+docs-build/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+

.prettierrc

@@ -0,0 +1,2 @@
+printWidth: 80
+proseWrap: "always"

CONTRIBUTING.md

@@ -60,3 +60,7 @@ Binaries can be created automatically using `make dist-linux` and `make dist-mac
 Unfortunately, `make dist-macos` must be run manually on both an Apple Silicon and Intel chips. The Linux builds are created using Docker and [these custom images](https://github.com/zk-org/zk-xcompile), which are hosted via [ghcr.io within zk-org](https://github.com/orgs/zk-org/packages/container/package/zk-xcompile).
 
 This process is convoluted because `zk` requires CGO with `mattn/go-sqlite3`, which prevents using Go's native cross-compilation. Transitioning to a CGO-free SQLite driver such as [cznic/sqlite](https://gitlab.com/cznic/sqlite) could simplify the distribution process significantly.
+
+## Documentation
+
+TODO: add documentation steps for Sphinx docs, after it's all working.

Makefile

@@ -60,10 +60,17 @@ dist-alpine-i386:
 		&& docker run --rm -v "${PWD}":/usr/src/zk -w /usr/src/zk ghcr.io/zk-org/zk-xcompile:alpine-i386 /bin/bash -c 'make alpine' \
 		&& tar -zcvf "zk-${VERSION}-alpine-i386.tar.gz" zk
 
-# Clean build products.
+# Clean build and docs products.
 clean:
 	rm -rf zk*
+	rm -rf docs-build
 
+### Sphinx Docs ###
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+docs: Makefile
+	mkdir -p docs-build
+	sphinx-build -a docs docs-build 
 
 VERSION := `git describe --tags --match v[0-9]* 2> /dev/null`
 BUILD := `git rev-parse --short HEAD`

docs/.zk/config.toml

@@ -0,0 +1,197 @@
+# zk configuration file
+#
+# Uncomment the properties you want to customize.
+
+# NOTE SETTINGS
+#
+# Defines the default options used when generating new notes.
+[note]
+
+# Language used when writing notes.
+# This is used to generate slugs or with date formats.
+#language = "en"
+
+# The default title used for new note, if no `--title` flag is provided.
+#default-title = "Untitled"
+
+# Template used to generate a note's filename, without extension.
+#filename = "{{id}}"
+
+# The file extension used for the notes.
+#extension = "md"
+
+# Template used to generate a note's content.
+# If not an absolute path or "~/unix/path", it's relative to .zk/templates/
+template = "default.md"
+
+# Path globs ignored while indexing existing notes.
+#ignore = [
+#    "drafts/*",
+#	"log.md"
+#]
+
+# Configure random ID generation.
+
+# The charset used for random IDs. You can use:
+#   * letters: only letters from a to z.
+#   * numbers: 0 to 9
+#   * alphanum: letters + numbers
+#   * hex: hexadecimal, from a to f and 0 to 9
+#   * custom string: will use any character from the provided value
+#id-charset = "alphanum"
+
+# Length of the generated IDs.
+#id-length = 4
+
+# Letter case for the random IDs, among lower, upper or mixed.
+#id-case = "lower"
+
+
+# EXTRA VARIABLES
+#
+# A dictionary of variables you can use for any custom values when generating
+# new notes. They are accessible in templates with {{extra.<key>}}
+[extra]
+
+#key = "value"
+
+
+# GROUP OVERRIDES
+#
+# You can override global settings from [note] and [extra] for a particular
+# group of notes by declaring a [group."<name>"] section.
+#
+# Specify the list of directories which will automatically belong to the group
+# with the optional `paths` property.
+#
+# Omitting `paths` is equivalent to providing a single path equal to the name of
+# the group. This can be useful to quickly declare a group by the name of the
+# directory it applies to.
+
+#[group."<NAME>"]
+#paths = ["<DIR1>", "<DIR2>"]
+#[group."<NAME>".note]
+#filename = "{{format-date now}}"
+#[group."<NAME>".extra]
+#key = "value"
+
+
+# MARKDOWN SETTINGS
+[format.markdown]
+
+# Format used to generate links between notes.
+# Either "wiki", "markdown" or a custom template. Default is "markdown".
+#link-format = "wiki"
+# Indicates whether a link's path will be percent-encoded.
+# Defaults to true for "markdown" format and false for "wiki" format.
+#link-encode-path = true
+# Indicates whether a link's path file extension will be removed.
+# Defaults to true.
+#link-drop-extension = true
+
+# Enable support for #hashtags.
+hashtags = true
+# Enable support for :colon:separated:tags:.
+colon-tags = false
+# Enable support for Bear's #multi-word tags#
+# Hashtags must be enabled for multi-word tags to work.
+multiword-tags = false
+
+
+# EXTERNAL TOOLS
+[tool]
+
+# Default editor used to open notes. When not set, the EDITOR or VISUAL
+# environment variables are used.
+#editor = "vim"
+
+# Pager used to scroll through long output. If you want to disable paging
+# altogether, set it to an empty string "".
+#pager = "less -FIRX"
+
+# Command used to preview a note during interactive fzf mode.
+# Set it to an empty string "" to disable preview.
+
+# bat is a great tool to render Markdown document with syntax highlighting.
+#https://github.com/sharkdp/bat
+#fzf-preview = "bat -p --color always {-1}"
+
+
+# LSP
+#
+#   Configure basic editor integration for LSP-compatible editors.
+#   See https://github.com/zk-org/zk/blob/main/docs/editors-integration.md
+#
+[lsp]
+
+[lsp.diagnostics]
+# Each diagnostic can have for value: none, hint, info, warning, error
+
+# Report titles of wiki-links as hints.
+#wiki-title = "hint"
+# Warn for dead links between notes.
+dead-link = "error"
+
+[lsp.completion]
+# Customize the completion pop-up of your LSP client.
+
+# Show the note title in the completion pop-up, or fallback on its path if empty.
+#note-label = "{{title-or-path}}"
+# Filter out the completion pop-up using the note title or its path.
+#note-filter-text = "{{title}} {{path}}"
+# Show the note filename without extension as detail.
+#note-detail = "{{filename-stem}}"
+
+
+# NAMED FILTERS
+#
+#    A named filter is a set of note filtering options used frequently together.
+#
+[filter]
+
+# Matches the notes created the last two weeks. For example:
+#    $ zk list recents --limit 15
+#    $ zk edit recents --interactive
+#recents = "--sort created- --created-after 'last two weeks'"
+
+
+# COMMAND ALIASES
+#
+#   Aliases are user commands called with `zk <alias> [<flags>] [<args>]`.
+#
+#   The alias will be executed with `$SHELL -c`, please refer to your shell's
+#   man page to see the available syntax. In most shells:
+#     * $@ can be used to expand all the provided flags and arguments
+#     * you can pipe commands together with the usual | character
+#
+[alias]
+# Here are a few aliases to get you started.
+
+# Shortcut to a command.
+#ls = "zk list $@"
+
+# Default flags for an existing command.
+#list = "zk list --quiet $@"
+
+# Edit the last modified note.
+#editlast = "zk edit --limit 1 --sort modified- $@"
+
+# Edit the notes selected interactively among the notes created the last two weeks.
+# This alias doesn't take any argument, so we don't use $@.
+#recent = "zk edit --sort created- --created-after 'last two weeks' --interactive"
+
+# Print paths separated with colons for the notes found with the given
+# arguments. This can be useful to expand a complex search query into a flag
+# taking only paths. For example:
+#   zk list --link-to "`zk path -m potatoe`"
+#path = "zk list --quiet --format {{path}} --delimiter , $@"
+
+# Show a random note.
+#lucky = "zk list --quiet --format full --sort random --limit 1"
+
+# Returns the Git history for the notes found with the given arguments.
+# Note the use of a pipe and the location of $@.
+#hist = "zk list --format path --delimiter0 --quiet $@ | xargs -t -0 git log --patch --"
+
+# Edit this configuration file.
+#conf = '$EDITOR "$ZK_NOTEBOOK_DIR/.zk/config.toml"'

docs/.zk/templates/default.md

@@ -0,0 +1,3 @@
+# {{title}}
+
+{{content}}

docs/automation.md

@@ -0,0 +1,30 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "zk"
+copyright = "2024, zk-org"
+author = "zk-org"
+release = "0.14.1"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["myst_parser"]
+myst_enable_extensions = ["colon_fence", "html_image"]
+suppress_warnings = ["myst.xref_missing", "myst.iref_ambiguous"]
+
+templates_path = ["_templates"]
+exclude_patterns = [".zk"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]
+master_doc = "index"