Documentation site (#745)

.github/workflows/doc.yml

@@ -61,3 +61,39 @@ jobs:
           git config --global user.name = "${{ github.actor }}"
           git commit -a -m "update docs for ${GITHUB_REF##*/}"
           git push origin gh-pages
+
+  update_site:
+    if: github.ref == 'refs/heads/master'
+    name: 'Rebuild website'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+
+      - name: Generate website
+        run: pip install mkdocs-material && mkdocs build
+
+      - name: Clone the gh-pages branch
+        uses: actions/checkout@v2
+        with:
+          repository: status-im/nim-libp2p
+          ref: gh-pages
+          path: subdoc
+          fetch-depth: 0
+
+      - name: Commit & push
+        run: |
+          cd subdoc
+
+          rm -rf docs
+          mv ../site docs
+
+          git add .
+          git config --global user.email "${{ github.actor }}@users.noreply.github.com"
+          git config --global user.name = "${{ github.actor }}"
+          git commit -a -m "update website"
+          git push origin gh-pages

README.md

@@ -49,9 +49,7 @@ nimble install libp2p
 ```
 
 ## Getting Started
-You'll find some tutorials [here](examples/tutorial_1_connect.md), or some examples:
+You'll find the documentation [here].(https://status-im.github.io/nim-libp2p/docs/)
-- [hello world (ping)](examples/helloworld.nim)
-- [direct chat](examples/directchat.nim)
 
 **Go Daemon:**
 Please find the installation and usage intructions in [daemonapi.md](examples/go-daemon/daemonapi.md).
@@ -114,8 +112,6 @@ nimble install
 # run all the unit tests
 nimble test
 ```
-The code follows the [Status Nim Style Guide](https://status-im.github.io/nim-style-guide/).
-
 
 ### Contribute
 

examples/README.md

@@ -0,0 +1,6 @@
+# nim-libp2p documentation
+
+Welcome to the nim-libp2p documentation!
+
+Here, you'll find [tutorials](tutorial_1_connect.md) to help you get started, as well as [examples](directchat.nim) and
+the [full reference](https://status-im.github.io/nim-libp2p/master/libp2p.html).

examples/tutorial_1_connect.md

@@ -1,15 +1,18 @@
-Hi all, welcome to the first article of the nim-libp2p's tutorial series!
+# Simple ping tutorial
 
-_This tutorial is for everyone who is interested in building peer-to-peer chatting applications. No Nim programming experience is needed._
+Hi all, welcome to the first nim-libp2p tutorial!
+
+!!! tips ""
+    This tutorial is for everyone who is interested in building peer-to-peer applications. No Nim programming experience is needed.
 
 To give you a quick overview, **Nim** is the programming language we are using and **nim-libp2p** is the Nim implementation of [libp2p](https://libp2p.io/), a modular library that enables the development of peer-to-peer network applications.
 
 Hope you'll find it helpful in your journey of learning. Happy coding! ;)
 
-# Before you start
+## Before you start
 The only prerequisite here is [Nim](https://nim-lang.org/), the programming language with a Python-like syntax and a performance similar to C. Detailed information can be found [here](https://nim-lang.org/docs/tut1.html).
 
-Install Nim via their official website: [https://nim-lang.org/install.html](https://nim-lang.org/install.html)  
+Install Nim via their [official website](https://nim-lang.org/install.html).
 Check Nim's installation via `nim --version` and its package manager Nimble via `nimble --version`.
 
 You can now install the latest version of `nim-libp2p`:
@@ -17,10 +20,11 @@ You can now install the latest version of `nim-libp2p`:
 nimble install libp2p@#master
 ```
 
-# A simple ping application
+## A simple ping application
 We'll start by creating a simple application, which is starting two libp2p [switch](https://docs.libp2p.io/concepts/stream-multiplexing/#switch-swarm), and pinging each other using the [Ping](https://docs.libp2p.io/concepts/protocols/#ping) protocol.
 
-_TIP: You can extract the code from this tutorial by running `nim c -r tools/markdown_runner.nim examples/tutorial_1_connect.md` in the libp2p folder!_
+!!! tips ""
+    You can extract the code from this tutorial by running `nim c -r tools/markdown_runner.nim examples/tutorial_1_connect.md` in the libp2p folder!
 
 Let's create a `part1.nim`, and import our dependencies:
 ```nim
@@ -61,7 +65,7 @@ proc main() {.async, gcsafe.} =
 We created some variables that we'll need for the rest of the application: the global `rng` instance, our `localAddress`, and an instance of the `Ping` protocol.
 The address is in the [MultiAddress](https://github.com/multiformats/multiaddr) format. The port `0` means "take any port available".
 
-`tryGet` is procedure which is part of the [nim-result](https://github.com/arnetheduck/nim-result/), that will throw an exception if the supplied MultiAddress is not valid.
+`tryGet` is procedure which is part of [nim-result](https://github.com/arnetheduck/nim-result/), that will throw an exception if the supplied MultiAddress is invalid.
 
 We can now create our two switches:
 ```nim

examples/tutorial_2_customproto.md

@@ -1,8 +1,9 @@
+# Custom protocol in libp2p
+
 In the [previous tutorial](tutorial_1_connect.md), we've looked at how to create a simple ping program using the `nim-libp2p`.
 
 We'll now look at how to create a custom protocol inside the libp2p
 
-# Custom protocol in libp2p
 Let's create a `part2.nim`, and import our dependencies:
 ```nim
 import chronos
@@ -29,6 +30,8 @@ Let's start with the server part:
 proc new(T: typedesc[TestProto]): T =
   # every incoming connections will in be handled in this closure
   proc handle(conn: Connection, proto: string) {.async, gcsafe.} =
+    # Read up to 1024 bytes from this connection, and transform them into
+    # a string
     echo "Got from remote - ", string.fromBytes(await conn.readLp(1024))
     # We must close the connections ourselves when we're done with it
     await conn.close()
@@ -69,7 +72,7 @@ proc main() {.async, gcsafe.} =
   await allFutures(switch1.stop(), switch2.stop()) # close connections and shutdown all transports
 ```
 
-This is very similar to the first tutorial's `main`, the only noteworthy difference is that we use `newStandardSwitch`, which is similar to `createSwitch` but is bundled directly in libp2p
+This is very similar to the first tutorial's `main`, the only noteworthy difference is that we use `newStandardSwitch`, which is similar to the `createSwitch` of the first tutorial, but is bundled directly in libp2p
 
 We can now wrap our program by calling our main proc:
 ```nim

libp2p.nim

@@ -8,7 +8,7 @@
 # those terms.
 
 when defined(nimdoc):
-  ## Welcome to the nim-libp2p documentation!
+  ## Welcome to the nim-libp2p reference!
   ##
   ## On the left, you'll find a switch that allows you to see private
   ## procedures. By default, you'll only see the public one (marked with `{.public.}`)

mkdocs.yml

@@ -0,0 +1,45 @@
+site_name: nim-libp2p
+
+repo_url: https://github.com/status-im/nim-libp2p
+repo_name: status-im/nim-libp2p
+site_url: https://status-im.github.io/nim-libp2p/docs
+edit_uri: edit/unstable/examples/
+
+docs_dir: examples
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+
+theme:
+  logo: https://docs.libp2p.io/images/logo_small.png
+  favicon: https://docs.libp2p.io/images/logo_small.png
+  name: material
+  features:
+    - navigation.instant
+    - search.highlight
+  palette:
+    - scheme: default
+      primary: blue grey
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to dark mode
+
+    - scheme: slate
+      primary: blue grey
+      toggle:
+        icon: material/toggle-switch-off-outline
+        name: Switch to light mode
+
+nav:
+  - Introduction: README.md
+  - Tutorials:
+    - 'Part I: Simple connection': tutorial_1_connect.md
+    - 'Part II: Custom protocol': tutorial_2_customproto.md
+  - Reference: '/nim-libp2p/master/libp2p.html'