Documentation update

README.md

@@ -6,11 +6,10 @@
 
 ## About
 As I wanted a wiki that just uses plain markdown files as backend, that is easy
-to use and that is written in python, to enable me to easily hack around,
+to use and that is written in a python, to enable me to easily hack around,
 but found nothing, I just wrote this down. I hope that it might help others ,too.
 
 ## Features
-
 * Markdown Syntax Editing
 * Tags
 * Regex Search
@@ -23,32 +22,38 @@ but found nothing, I just wrote this down. I hope that it might help others ,too
 	* and many more
 
 ### Planned
-
 * Re-introduce support for customizing the theme
 * Speed Improvements
 	* Code Optimizations
 	* Caching
 * Settings via the webinterface
 
-
 ## Setup
-You can install wiki using:
+You can install the wiki using:
 
 	pip install wiki2
 
-
 Afterwards you can create or change into your content directory and create a `config.py` file in it, that contains at least the following:
 
 	# encoding: <your encoding (probably utf-8)
-	SECRET_KEY='a unique and long key'
-	TITLE='Wiki' # Title Optional
+	SECRET_KEY='an unique and long key'
+
+Other options described in [Usage](doc/Usage.md).
 
 ## Usage
-Afterwards you can just run `wiki web` in your content directory to start the server.
+Afterwards you can just run `wiki web` in your content directory to start the server.  
+Additional run options described in [Usage](doc/Usage.md).  
+Deploing wiki behind Apache web-server described in [Apache](doc/Apache.md).
 
 ## Development
 If you plan on helping with the development of this project you can clone the repository, open the newly created directory in a terminal and run `pip install -e .`, after which both the tests and the wiki cli will be available to you.
 
-## Contributors
+## 3rd parties
+Wiki is bundled together with 3rd-party JavaScript/CSS libraries:
+- [bootstrap](https://getbootstrap.com)
+- [jquery](https://jquery.com)
+- tex-svg (part of [MathJax](https://github.com/mathjax/MathJax))
 
-Thank you very much to my two top contributers @walkerh and @traeblain. You two have posted so many issues and especially solved them with so many pull requests, that I sometimes lose track of it! :)
+
+## Contributors
+Thank you very much to my two top contributers @walkerh and @traeblain. You two have posted so many issues and especially solved them with so many pull requests, that I sometimes lose a track of it! :)

doc/Apache.md

@@ -0,0 +1,61 @@
+# Apache
+
+Let's use wiki as WSGI application of Apache web-server.
+
+Pre-conditions:
+
+- Wiki is istalled as system-wide python3 library.
+- data will be in `/var/lib/mynotes`.
+- URL will be `http[s]://www.mysite.com/notes/`, so this will be WSGI application in virtual web-folder.
+- RH-based Linux distro.
+
+---
+
+1. Apache config
+
+    `/etc/httpd/conf.d/wiki.conf`:
+    ```apache
+    # don't forget 2 lines below to prevent non-ascii filenames error
+    WSGIDaemonProcess apache lang=en_US.UTF-8 locale=C.UTF-8
+    WSGIProcessGroup apache
+    WSGIScriptAlias /notes /user/share/wiki/wiki.wsgi
+    <Location /notes>
+       Require all granted
+    </Location>
+    ```
+
+1. WSGI app
+
+    `/user/share/wiki/wiki.wsgi`:
+    ```python
+    #!/usr/bin/env python3
+    import sys
+    import logging
+    from wiki.web import create_app
+
+    logging.basicConfig(stream=sys.stderr)
+    application = create_app("/etc/wiki/")
+    ```
+
+1. Wiki config
+
+    `/etc/wiki/config.py`:
+    ```python
+    # encoding: utf-8
+    SECRET_KEY='anuniqueandlongkey'
+    TITLE='My Own Wiki'
+    CONTENT_DIR='/var/lib/mynotes'
+    ```
+
+1. Wiki storage
+    ```bash
+    mkdir -p /var/lib/mynotes
+    chown apache:apache /var/lib/mynotes
+    ```
+
+1. The end
+
+    `sudo systemctl restart httpd` and goto `http://www.mysite.com/notes/`
+
+---
+*TODO: users.json, auth*

doc/Usage.md

@@ -0,0 +1,73 @@
+# Usage
+
+## 1. Running wiki
+
+Beheviour of wiki depend on environment variables, command line options and/or config files.
+
+### 1.1. Environment variables
+- `WIKI_HOST=...` - IP that wiki listens on (default 127.0.0.1; set 0.0.0.0 for everybody)
+- `WIKI_PORT=...` - TCP port that wiki listens on (default 5000)
+- `WIKI_DEBUG` - vebosity on
+
+### 1.2. CLI options
+Common wiki run as standalone application is:
+
+    wiki [--directory=...] web [--host=...] [--port=...] [--debug]
+
+Where:
+- `--directory` - path of folder where config.py lives (default - current folder)
+- `--host` - see `WIKI_HOST` above
+- `--port` - see `WIKI_PORT` above
+- `--debug` - see `WIKI_DEBUG` above
+
+### 1.3. config.py
+
+This file *must* exist and contains mostly optional definitions:
+
+```python
+SECRET_KEY = 'an unique and long key'        # mandatory
+TITLE = 'Wiki title'                         # default 'wiki'
+CONTENT_DIR = '/path/to/markdown/files/dir'  # default = --directory above
+DEFAULT_AUTHENTICATION_METHOD='hash'         # 'hash' or 'cleartext' (default)
+PRIVATE=True                                 # Access denied for anonymous' (default=False)
+DEBUG = True                                 # default False
+```
+
+### 1.4. users.json
+
+Users creditentials file is stored in CONTENT_DIR (right near *.md).
+Sample of 1 user `user` with password `password` looks like:
+```json
+{
+  "user": {
+    "active": true,
+    "roles": [],
+    "authentication_method": "cleartext",
+    "authenticated": true,
+    "password": "password"
+  }
+}
+```
+
+### 1.5. Run from sources
+
+To run wiki right in git clone dir:
+```python
+from wiki.web import create_app
+app = create_app('/see/--directory/above')
+app.run()   # add host=..., port=..., debug=...
+```
+
+## 2. Wiki features
+
+### 2.1. Local URLs
+- `[[Wiki Links]] stay [[wiki_link]] (lowercase and undescored)
+- `[Ordinary links](Target File)` stay `<currentpage>/Target File.md`
+- root page is exectly `home.md`
+- folders and files right in CONTENT_DIR root connot be named as reserved actions:
+  *home, index, create, edit, preview, move, delete, tags, tag, search, user*.
+
+### 2.2. Importing *.md
+You can just copy your existant *.md into CONTENT_DIR but with the only conditions:
+- file *should* have *optional* [meta-data](https://python-markdown.github.io/extensions/meta_data/) lines `title: ...` and `tags: ...`
+- file can be `Camel Case.md`, `Camel_Case.md`, `camel case.md` or `camel_case.md`, but `[[Wiki Link]]` will try to get `wiki_link.md` only.