Mkdocs unify docs (#3999)

* basic mkdocs setup and workflow

* rename workflow

* copy lettuce

* add index

* integrate current wiki and docs content

* integrate current wiki and docs content

* add a few more links

* fix branch in actions

* remove redundant getting started and maven docs

* Revert jedis-maven doc deletion

* Exclude Dockerfile and css from spellcheck

* Fix spelling

* Remove assets from spellcheck-settings.yml

* Add build for dev branch

* Another attempt to fix spellcheck

* Add some words to wordlist

* Add more words to wordlist

* Update .github/workflows/docs.yml

Co-authored-by: M Sazzadul Hoque <[email protected]>

---------

Co-authored-by: Josh Rotenberg <[email protected]>
Co-authored-by: M Sazzadul Hoque <[email protected]>

.github/spellcheck-settings.yml

@@ -25,4 +25,5 @@ matrix:
       - img
   sources:
   - '*.md'
-  - 'docs/**'
+  - 'docs/*.md'
+

.github/wordlist.txt

@@ -1,6 +1,7 @@
 !!!Spelling check failed!!!
 APM
 ARGV
+BaseObjectPoolConfig
 BFCommands
 BitOP
 BitPosParams
@@ -16,6 +17,7 @@ ClusterPipeline
 ClusterPubSub
 ConnectionPool
 CoreCommands
+Dockerfile
 EVAL
 EVALSHA
 Failback
@@ -46,6 +48,7 @@ JedisCluster
 JedisConnectionException
 JedisPool
 JedisPooled
+JedisPubSub
 JedisShardInfo
 ListPosition
 Ludovico
@@ -174,6 +177,7 @@ incr
 incrBy
 incrByFloat
 ini
+io
 json
 keyslot
 keyspace
@@ -198,6 +202,9 @@ mget
 microservice
 microservices
 millisecondsTimestamp
+MkDocs
+mkdocs
+md
 mset
 msetnx
 multikey
@@ -224,6 +231,7 @@ pubsub
 punsubscribe
 py
 pypi
+PoolConfig
 quickstart
 readonly
 readwrite
@@ -234,10 +242,12 @@ reinitialization
 renamenx
 replicaof
 repo
+README
 rpush
 rpushx
 runtime
 sadd
+SafeEncoder
 scard
 scoreMembers
 sdiffstore
@@ -260,6 +270,7 @@ strlen
 stunnel
 subcommands
 sunionstore
+pipelining
 thevalueofmykey
 timeseries
 toctree
@@ -311,3 +322,4 @@ zrevrangeByScore
 zrevrangeByScoreWithScores
 zrevrangeWithScores
 zunionstore
+yml

.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+name: Publish Docs
+on:
+  push:
+    branches: ["master"]
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+jobs:
+  build-and-deploy:
+    concurrency: ci-${{ github.ref }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material pymdown-extensions mkdocs-macros-plugin
+      - name: Build docs
+        run: |
+          mkdocs build -d docsbuild
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: 'docsbuild'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

docs/Dockerfile

@@ -0,0 +1,3 @@
+FROM squidfunk/mkdocs-material
+RUN pip install mkdocs-macros-plugin
+RUN pip install mkdocs-glightbox

docs/README.md

@@ -0,0 +1,15 @@
+# Jedis Documentation
+
+This documentation uses [MkDocs](https://www.mkdocs.org/) to generate the static site.
+
+See [mkdocs.yml](../mkdocs.yml) for the configuration. 
+
+To develop the documentation locally, you can use the included [Dockerfile](Dockerfile) to build a container with all the 
+dependencies, and run it to preview your changes:
+
+```bash
+# in docs/
+docker build -t squidfunk/mkdocs-material .
+# cd ..
+docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material 
+```

docs/advanced-usage.md

@@ -0,0 +1,135 @@
+# Advanced Usage
+
+## Transactions
+
+To do transactions in Jedis, you have to wrap operations in a transaction block, very similar to pipelining:
+
+```java
+jedis.watch (key1, key2, ...);
+Transaction t = jedis.multi();
+t.set("foo", "bar");
+t.exec();
+```
+
+Note: when you have any method that returns values, you have to do like this:
+
+
+```java
+Transaction t = jedis.multi();
+t.set("fool", "bar"); 
+Response<String> result1 = t.get("fool");
+
+t.zadd("foo", 1, "barowitch"); t.zadd("foo", 0, "barinsky"); t.zadd("foo", 0, "barikoviev");
+Response<Set<String>> sose = t.zrange("foo", 0, -1);   // get the entire sortedset
+t.exec();                                              // dont forget it
+
+String foolbar = result1.get();                       // use Response.get() to retrieve things from a Response
+int soseSize = sose.get().size();                      // on sose.get() you can directly call Set methods!
+
+// List<Object> allResults = t.exec();                 // you could still get all results at once, as before
+```
+Note that a Response Object does not contain the result before t.exec() is called (it is a kind of a Future). Forgetting exec gives you exceptions. In the last lines, you see how transactions/pipelines were dealt with before version 2. You can still do it that way, but then you need to extract objects from a list, which contains also Redis status messages.
+
+Note 2: Redis does not allow to use intermediate results of a transaction within that same transaction. This does not work:
+
+```java
+// this does not work! Intra-transaction dependencies are not supported by Redis!
+jedis.watch(...);
+Transaction t = jedis.multi();
+if(t.get("key1").equals("something"))
+   t.set("key2", "value2");
+else 
+   t.set("key", "value");
+```
+
+However, there are some commands like setnx, that include such a conditional execution. Those are of course supported within transactions. You can build your own customized commands using EVAL / LUA scripting. 
+
+
+## Pipelining
+
+Sometimes you need to send a bunch of different commands. A very cool way to do that, and have better performance than doing it the naive way, is to use pipelining. This way you send commands without waiting for response, and you actually read the responses at the end, which is faster. 
+
+Here is how to do it:
+
+```java
+Pipeline p = jedis.pipelined();
+p.set("fool", "bar"); 
+p.zadd("foo", 1, "barowitch");  p.zadd("foo", 0, "barinsky"); p.zadd("foo", 0, "barikoviev");
+Response<String> pipeString = p.get("fool");
+Response<Set<String>> sose = p.zrange("foo", 0, -1);
+p.sync(); 
+
+int soseSize = sose.get().size();
+Set<String> setBack = sose.get();
+```
+For more explanations see code comments in the transaction section.
+
+
+## Publish/Subscribe
+
+To subscribe to a channel in Redis, create an instance of JedisPubSub and call subscribe on the Jedis instance:
+
+```java
+class MyListener extends JedisPubSub {
+        public void onMessage(String channel, String message) {
+        }
+
+        public void onSubscribe(String channel, int subscribedChannels) {
+        }
+
+        public void onUnsubscribe(String channel, int subscribedChannels) {
+        }
+
+        public void onPSubscribe(String pattern, int subscribedChannels) {
+        }
+
+        public void onPUnsubscribe(String pattern, int subscribedChannels) {
+        }
+
+        public void onPMessage(String pattern, String channel, String message) {
+        }
+}
+
+MyListener l = new MyListener();
+
+jedis.subscribe(l, "foo");
+```
+Note that subscribe is a blocking operation because it will poll Redis for responses on the thread that calls subscribe.  A single JedisPubSub instance can be used to subscribe to multiple channels.  You can call subscribe or psubscribe on an existing JedisPubSub instance to change your subscriptions.
+
+
+### Monitoring
+
+To use the monitor command you can do something like the following:
+
+```java
+new Thread(new Runnable() {
+    public void run() {
+        Jedis j = new Jedis("localhost");
+        for (int i = 0; i < 100; i++) {
+            j.incr("foobared");
+            try {
+                Thread.sleep(200);
+            } catch (InterruptedException e) {
+            }
+        }
+        j.disconnect();
+    }
+}).start();
+
+jedis.monitor(new JedisMonitor() {
+    public void onCommand(String command) {
+        System.out.println(command);
+    }
+});
+```
+
+## Miscellaneous 
+
+### A note about String and Binary - what is native?
+
+Redis/Jedis talks a lot about Strings. And here [[http://redis.io/topics/internals]] it says Strings are the basic building block of Redis. However, this stress on strings may be misleading. Redis' "String" refer to the C char type (8 bit), which is incompatible with Java Strings (16-bit). Redis sees only 8-bit blocks of data of predefined length, so normally it doesn't interpret the data (it's "binary safe"). Therefore in Java, byte[] data is "native", whereas Strings have to be encoded before being sent, and decoded after being retrieved by the SafeEncoder. This has some minor performance impact.
+In short: if you have binary data, don't encode it into String, but use the binary versions.
+
+### A note on Redis' master/slave distribution
+
+A Redis network consists of redis servers, which can be either masters or slaves. Slaves are synchronized to the master (master/slave replication). However, master and slaves look identical to a client, and slaves do accept write requests, but they will not be propagated "up-hill" and could eventually be overwritten by the master. It makes sense to route reads to slaves, and write demands to the master. Furthermore, being a slave doesn't prevent from being considered master by another slave.

docs/css/extra.css

@@ -0,0 +1,4 @@
+/* extra.css */
+.md-header {
+    background-color: #FB2A2C; 
+}

docs/faq.md

@@ -0,0 +1,44 @@
+# Frequently Asked Questions
+
+## If you get `java.net.SocketTimeoutException: Read timed out` exception
+
+Try setting own `timeout` value when constructing `JedisPool` using the following constructor:
+```java
+JedisPool(GenericObjectPoolConfig poolConfig, String host, int port, int timeout)
+```
+where `timeout` is given as milliseconds.
+
+Default `timeout` value is **2 seconds**.
+
+## JedisPool blocks after getting 8 connections
+
+JedisPool defaults to 8 connections, you can change this in the PoolConfig:
+
+```java
+JedisPoolConfig poolConfig = new JedisPoolConfig();
+poolConfig.setMaxTotal(maxTotal); // maximum active connections
+poolConfig.setMaxIdle(maxIdle);  // maximum idle connections
+```
+
+Take into account that `JedisPool` inherits commons-pool [BaseObjectPoolConfig](https://commons.apache.org/proper/commons-pool/api-2.3/org/apache/commons/pool2/impl/BaseObjectPoolConfig.html) which has a lot of configuration parameters. 
+We've set some defined ones which suit most of the cases. In case, you experience [issues](https://github.com/xetorthio/jedis/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+JedisPool) tuning these parameters may help.
+
+## How to configure the buffer size of socket(s)
+
+The buffer size of all Jedis sockets in an application can be configured through system property.
+
+Buffer size of input stream can be configured by setting `jedis.bufferSize.input` or `jedis.bufferSize` system property.  
+Buffer size of output stream can be configured by setting `jedis.bufferSize.output` or `jedis.bufferSize` system property.  
+If you want to set the buffer size of both input and output stream to same value, you can just set `jedis.bufferSize`.
+
+Note: This feature is available since Jedis 4.2.0.
+
+## How to avoid cluster initialization error
+
+As of Jedis 4.0.0, a `JedisClusterOperationException` is raised with the message `Could not initialize cluster slots cache.` when the cluster initialization process fails. 
+
+Should you would want to avoid this error (for example, creating `JedisConnectionFactory` to an unavailable cluster for a spring-data-redis `Bean`), set the system property `jedis.cluster.initNoError` to any value.  
+In the console, add the option `-Djedis.cluster.initNoError`.
+In an application, `System.setProperty("jedis.cluster.initNoError", "");` can be set before creating any cluster object.
+
+Note: This feature is available since Jedis 4.4.2.

docs/index.md

@@ -0,0 +1 @@
+{% include 'README.md' %}

mkdocs.yml

@@ -0,0 +1,35 @@
+site_name: Jedis
+repo_name: Jedis
+site_author: Redis, Inc.
+site_description: Jedis is a Redis client for the JVM.
+repo_url: https://github.com/redis/jedis
+remote_branch: gh-pages
+
+theme:
+  name: material
+  logo: assets/images/logo.png
+  favicon: assets/images/favicon-16x16.png
+extra_css:
+  - css/extra.css
+
+plugins:
+  - search
+  - macros:
+      include_dir: .
+
+nav:
+  - Home: index.md
+  - Migrating from older versions:
+      - 3 to 4:
+        - Breaking changes: 3to4.md
+        - Primitives: 3to4-primitives.md
+        - ZSET: 3to4-zset-list.md
+  - Using Jedis with ...:
+    - Search: redisearch.md
+    - JSON: redisjson.md
+  - Failover: failover.md
+  - FAQ: faq.md
+  - API Reference: https://www.javadoc.io/doc/redis.clients/jedis/latest/index.html
+  - Jedis Guide: https://redis.io/docs/latest/develop/connect/clients/java/jedis/
+  - Redis Command Reference: https://redis.io/docs/latest/commands/
+