Ease contributing by improving CONTRIBUTING.md and Makefile (#66)

* feat(makefile): add user-docs target and more docs

* doc(CONTRIBUTING): move to root and add more details

* fix: wrong escaping

Author: sotte

.github/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing to `obsidian.nvim`
+
+Thanks for considering contributing!
+Please read this document to learn the various steps you should take before submitting a pull request.
+
+## TL;DR
+
+- Start an issue to discuss the planned changes
+- To submit a pull request
+  - Start developing your feature in a branch
+  - Make sure that your codes complies the `obsidian.nvim` code style, run
+    `make chores`
+  - The PR should contain
+    - The code changes
+    - Tests for the code changes
+    - Documentation for the code changes (in the code itself and in the `README.md`)
+    - `CHANGELOG.md` entry for the code changes
+
+## Details
+
+Note: we automate tedious tasks using a `Makefile` in the root of the repository.
+Just call `make` to see what you can do, or `make chores` to run the most important tasks on your code.
+You can override some parts of the `Makefile` by setting env variables.
+
+### Local development with LuaLS and `plenary.nvim`
+
+If you're using the [Lua Language Server](https://luals.github.io) (LuaLS) you'll probably want to add `plenary.nvim` as a workspace library since we rely heavily on plenary throughout the codebase.
+You can do this by adding a `.luarc.json` configuration file that looks like this:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
+  "workspace.library": ["~/.local/share/nvim/lazy/plenary.nvim/"],
+  "runtime.version": "Lua 5.1"
+}
+```
+
+Make sure that the path there to plenary is correct for you.
+
+### Keeping the `CHANGELOG.md` up-to-date
+
+This project tries hard to adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
+and we maintain a [`CHANGELOG`](https://github.com/obsidian-nvim/obsidian.nvim/blob/main/CHANGELOG.md)
+with a format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+If your PR addresses a bug or makes any other substantial change,
+please be sure to add an entry under the "Unreleased" section at the top of `CHANGELOG.md`.
+Entries should always be in the form of a list item under a level-3 header of either "Added", "Fixed", "Changed", or "Removed" for the most part.
+If the corresponding level-3 header for your item does not already exist in the "Unreleased" section, you should add it.
+
+### Formatting code
+
+TL;DR: `make style`
+
+Lua code should be formatted using [StyLua](https://github.com/JohnnyMorganz/StyLua).
+Once you have StyLua installed, you can run `make style` to automatically apply styling to all of the Lua files in this repo.
+
+### Linting code
+
+TL;DR: `make lint`
+
+We use [luacheck](https://github.com/mpeterv/luacheck) to lint the Lua code.
+Once you have `luacheck` installed, you can run `make lint` to get a report.
+
+### Running tests
+
+TL;DR: `make test`
+
+Tests are written in the `test/` folder and are run using the [Plenary](https://github.com/nvim-lua/plenary.nvim) test harness.
+Since Plenary is a dependency of `obsidian.nvim`, you probably already have it installed somewhere.
+To run the tests locally you'll need to know where it's installed, which depends on your plugin manager.
+In my case I use `Lazy.nvim` which puts Plenary at `~/.local/share/nvim/lazy/plenary.nvim/`.
+
+### Building the vim user documentation
+
+TL;DR: `make user-docs`
+
+The Vim documentation lives at `doc/obsidian.txt`, which is automatically generated from the `README.md` using [panvimdoc](https://github.com/kdheepak/panvimdoc).
+**Please only commit documentation changes to the `README.md`, not `doc/obsidian.txt`.**
+
+However you can test how changes to the README will affect the Vim doc by running `panvimdoc` locally.
+To do this you'll need install `pandoc` (e.g. `brew install pandoc` on Mac)
+and clone [panvimdoc](https://github.com/kdheepak/panvimdoc) (e.g. `git clone [email protected]:kdheepak/panvimdoc.git ../panvimdoc`).
+
+This will build the Vim documentation to `/tmp/obsidian.txt`.
+
+### Building the vim API documentation
+
+TL;DR: `make api-docs`
+
+The API docs lives in `doc/obsidian_api.txt` and is generated from the source code using [`mini.docs`](https://github.com/echasnovski/mini.doc).
+It is automatically generated via CI.

CONTRIBUTING.md

@@ -3,15 +3,30 @@ SHELL:=/usr/bin/env bash
 .DEFAULT_GOAL:=help
 PROJECT_NAME = "obsidian.nvim"
 TEST = test/obsidian
-# Depending on your setup you have to override the locations at runtime.
+
+# Depending on your setup you have to override the locations at runtime. E.g.:
+#   make test PLENARY=~/path/to/plenary.nvim
+#   make user-docs PANVIMDOC_PATH=~/path/to/panvimdoc/panvimdoc.sh
 PLENARY = ~/.local/share/nvim/lazy/plenary.nvim/
 MINIDOC = ~/.local/share/nvim/lazy/mini.doc/
+PANVIMDOC_PATH = ../panvimdoc/panvimdoc.sh
 
+################################################################################
+##@ Start here
+.PHONY: chores
+chores: style lint test ## Run develoment tasks (lint, style, test); PRs must pass this.
 
 ################################################################################
 ##@ Developmment
-.PHONY: chores
-chores: style lint test ## Run all develoment tasks
+.PHONY: lint
+lint: ## Lint the code with luacheck
+	luacheck .
+
+.PHONY: style
+style:  ## Format the code with stylua
+	stylua --check .
+
+# TODO: add type checking with lua-ls
 
 .PHONY: test
 test: $(PLENARY) ## Run unit tests
@@ -24,6 +39,24 @@ test: $(PLENARY) ## Run unit tests
 $(PLENARY):
 	git clone --depth 1 https://github.com/nvim-lua/plenary.nvim.git $(PLENARY)
 
+.PHONY: user-docs
+user-docs: ## Generate user documentation with panvimdoc
+	@if [ ! -f "$(PANVIMDOC_PATH)" ]; then \
+		echo "panvimdoc.sh not found at '$(PANVIMDOC_PATH)'. Make sure it is installed and check the path."; \
+		exit 1; \
+	fi
+	$(PANVIMDOC_PATH) \
+		--project-name obsidian \
+		--input-file README.md \
+		--toc false \
+		--description 'a plugin for writing and navigating an Obsidian vault' \
+		--vim-version 'NVIM v0.10.0' \
+		--demojify false \
+		--dedup-subheadings false \
+		--shift-heading-level-by -1 \
+		--ignore-rawblocks true \
+		&& mv doc/obsidian.txt /tmp/
+
 .PHONY: api-docs
 api-docs: $(MINIDOC) ## Generate API documentation with mini.doc
 	MINIDOC=$(MINIDOC) nvim \
@@ -36,14 +69,6 @@ api-docs: $(MINIDOC) ## Generate API documentation with mini.doc
 $(MINIDOC):
 	git clone --depth 1 https://github.com/echasnovski/mini.doc $(MINIDOC)
 
-.PHONY: lint
-lint: ## Lint the code
-	luacheck .
-
-.PHONY: style
-style:  ## format the code
-	stylua --check .
-
 
 ################################################################################
 ##@ Helpers

Makefile

@@ -809,7 +809,7 @@ And keep in mind that to reset a configuration option to `nil` you'll have to us
 
 ## Contributing
 
-Please read the [CONTRIBUTING](https://github.com/obsidian-nvim/obsidian.nvim/blob/main/.github/CONTRIBUTING.md) guide before submitting a pull request.
+Please read the [CONTRIBUTING](https://github.com/obsidian-nvim/obsidian.nvim/blob/main/CONTRIBUTING.md) guide before submitting a pull request.
 
 ## Acknowledgement