* docs: centralize documentation into helpdoc
Problem: documentation was spread across four files (README.md,
doc/oil.txt, doc/api.md, doc/recipes.md) with duplication and gaps.
User events were undocumented, and adapter docs only lived in the
README.
Solution: expand doc/oil.txt with five new sections (introduction,
requirements, adapters, recipes, events) from existing content. Trim
README to a landing page pointing to :help oil. Delete doc/api.md
and doc/recipes.md since their content now lives in the helpdoc.
Closes: barrettruth/oil.nvim#6
* build: remove docgen pipeline
Problem: the Python docgen pipeline (scripts/generate.py,
scripts/main.py, nvim_doc_tools) was designed for upstream's doc
layout and is incompatible with the centralized helpdoc structure.
It overwrites doc/oil.txt entirely and expects sections in README.md
that no longer exist.
Solution: delete the pipeline scripts (generate.py, main.py,
requirements.txt), remove the update_docs CI job, and clean up the
Makefile and .gitignore references. Linting and typechecking remain
unchanged.
Problem: the docgen workflow pushed directly to main, which is blocked
by repository rulesets. No token-based push from GitHub Actions can
bypass ruleset rules on personal repos.
Solution: replace the push step with a git diff --exit-code check that
fails if generated docs are out of date. Docs must now be committed by
the developer via make doc. Also regenerates docs to reflect batch 4
changes (close_float, OilFileIcon, OilExecutableHidden, recipe link).
Problem: the docgen workflow pushes to main using GITHUB_TOKEN, which
authenticates as github-actions[bot]. The bot cannot bypass repository
rulesets on personal repos, so the push is rejected by required PR,
status check, and signature rules.
Solution: prefer a PUSH_TOKEN secret (a PAT authenticated as the repo
admin, who has bypass permissions) with fallback to GITHUB_TOKEN so
the workflow does not break before the secret is created.
Problem: the fork used master as the default branch name.
Solution: rename to main and update all CI workflow triggers,
ref checks, and the pre-push hook fallback.
