Create "Nimble Guide" (#1190)

.gitignore

@@ -64,3 +64,7 @@ src/nimblepkg/version
 /buildTests
 /tests/nimdep/nimble.lock
 /tests/nimdep/localnimbledeps/
+
+# Nimble Guide files
+nimble-guide/site/
+!Makefile

Makefile

@@ -0,0 +1,18 @@
+publish-guide:
+ # CURRENT_BRANCH="$$(git rev-parse --abbrev-ref HEAD)"; \
+ # if [[ "$${CURRENT_BRANCH}" != "master" ]]; then \
+ # echo -e "\nWarning: you're publishing the books from the 'master' branch!\n"; \
+ # fi
+ CURRENT_COMMIT="$$(git rev-parse --short HEAD)" && \
+ cd nimble-guide && \
+ mkdocs build && \
+ cd .. && \
+ git worktree add tmp-book gh-pages && \
+ cp -a nimble-guide/site/* tmp-book/ && \
+ cd tmp-book && \
+ git add . && { \
+ git commit -m "make publish-guide $${CURRENT_COMMIT}" && \
+ git push origin gh-pages || true; } && \
+ cd .. && \
+ git worktree remove -f tmp-book && \
+ rm -rf tmp-book

nimble-guide/docs/config.md

@@ -0,0 +1,36 @@
+# Configuration
+
+At startup Nimble will attempt to read ``~/.config/nimble/nimble.ini`` on Linux (on Windows it will attempt to read ``C:\Users\<YourUser>\AppData\Roaming\nimble\nimble.ini``).
+
+The format of this file corresponds to the ini format with some Nim enhancements.
+For example:
+
+```ini
+nimbleDir = r"C:\Nimble\"
+
+[PackageList]
+name = "CustomPackages"
+url = "https://mydomain.org/packages.json"
+
+[PackageList]
+name = "Local project packages"
+path = r"C:\Projects\Nim\packages.json"
+```
+
+You can currently configure the following in this file:
+
+* `nimbleDir` - The directory which Nimble uses for package installation.
+ **Default:** `~/.nimble/`
+* `chcp` - Whether to change the current code page when executing Nim application packages.
+ If `true` this will add `chcp 65001` to the .cmd stubs generated in `~/.nimble/bin/`.
+ **Default:** `true`
+* `[PackageList]` + `name` + (`url` | `path`) - You can use this section to specify a new custom package list.
+ Multiple package lists can be specified.
+ Nimble defaults to the "Official" package list, you can override it by specifying a `[PackageList]` section named "official".
+ Multiple URLs can be specified under each section, Nimble will try each in succession if downloading from the first fails.
+ Alternatively, ``path`` can specify a local file path to copy a package list `.json` file from.
+* `cloneUsingHttps` - Whether to replace any `git:https://` inside URLs with `https://`.
+ **Default:** `true`
+* `httpProxy` - The URL of the proxy to use when downloading package listings.
+ Nimble will also attempt to read the `http_proxy` and `https_proxy` environment variables.
+ **Default:** `""`