General documentation updates

- We now have several developer-focused docs, so create an index page
  for them.
- Rework several docs to fit into the index structure.
- Experiment with code highlighting; tweak the CSS slightly to make
  it slightly nicer to look at.

Change-Id: I4185a18f84fa0764745ca7a3148276064a3155c6
Signed-off-by: Chris Luke <chrisy@flirble.org>

6 files changed, 41 insertions, 31 deletions

diff --git a/extras/libmemif/docs/BuildInstructions.md b/extras/libmemif/docs/buildinstructions_doc.md
index 9bb59b94c11..838e835a9a5 100644
--- a/extras/libmemif/docs/BuildInstructions.md
+++ b/extras/libmemif/docs/buildinstructions_doc.md
@@ -1,4 +1,4 @@
-## Build Instructions
+## Build Instructions    {#libmemif_build_doc}
 
 Install dependencies
 ```
@@ -49,6 +49,7 @@ commands:
 	ip-set <index> <ip-addr> - set interface ip address
 	rx-mode <index> <qid> <polling|interrupt> - set queue rx mode
 ```
+
 #### Examples
 
-Once the library is build/installed, refer to [Examples](../examples/README.md) and [Getting started](GettingStarted.md) for additional information on basic use cases and API usage.
+Once the library is built/installed, refer to @ref libmemif_examples_doc and @ref libmemif_gettingstarted_doc for additional information on basic use cases and API usage.
diff --git a/extras/libmemif/docs/GettingStarted.md b/extras/libmemif/docs/gettingstarted_doc.md
index 3cc0ceb0db1..e3ae6e5658e 100644
--- a/extras/libmemif/docs/GettingStarted.md
+++ b/extras/libmemif/docs/gettingstarted_doc.md
@@ -1,8 +1,8 @@
-## Getting started
+## Getting started    {#libmemif_gettingstarted_doc}
 
 #### Concept (Connecting to VPP)
 
-For detailed information on api calls and structures please refer to [libmemif.h](../src/libmemif.h)
+For detailed information on api calls and structures please refer to @ref libmemif.h.
 
 1. Initialize memif
    - Declare callback function handling file descriptor event polling.
@@ -152,7 +152,8 @@ if (err != MEMIF_ERR_SUCCESS)
 
 #### Example app (libmemif fd event polling):
 
-- [ICMP Responder](../examples/icmp_responder/main.c)
+- @ref extras/libmemif/examples/icmp_responder
+
 > Optional argument: transmit queue id.
 ```
 icmpr 1
@@ -162,11 +163,14 @@ icmpr 1
 
 #### Example app:
 
-- [ICMP Responder custom fd event polling](../examples/icmp_responder-epoll/main.c)
+ICMP Responder custom fd event polling.
+
+- @ref extras/libmemif/examples/icmp_responder-epoll
 
 #### Example app (multi-thread queue polling)
 
-- [ICMP Responder multi-thread](../examples/icmp_responder-mt/main.c)
+ICMP Responder multi-thread.
+- @ref extras/libmemif/examples/icmp_responder-mt
 
 > Simple example of libmemif multi-thread usage. Connection establishment is handled by main thread. There are two rx queues in this example. One in polling mode and second in interrupt mode.
 
diff --git a/extras/libmemif/examples/README.md b/extras/libmemif/examples/README.md
deleted file mode 100644
index 1375d27abae..00000000000
--- a/extras/libmemif/examples/README.md
+++ /dev/null
@@ -1,16 +0,0 @@
-## Examples
-
-After build, root folder will contain scripts linking binary examples with library (same name as example apps). These scripts can be executed to run example apps without installing the library. Example apps binaries can be found in _libs_ filder. To run binaries directly, make sure that libmemif library is installed.
-
-#### Run in container
-ligato/libmemif-sample-service image contains built and installed libmemf. To run different examples, override docker CMD to start container in bash:
-```
-# docker run -it --entrypoint=/bin/bash -i --rm --name icmp-responder --hostname icmp-responder --privileged -v "/run/vpp/:/run/vpp/" ligato/libmemif-sample-service
-```
-Current WORKDIR is set to root repository directory. Example apps can be run from this directory (a script linking binary with library), or browse to ./.libs folder and execute binary directly.
-
-Example app | Description
-------------|------------
-[icmpr](../examples/icmp_responder/main.c) | Simplest implementaion. Event polling is handled by libmemif. Single memif conenction in slave mode is created (id 0). Use Ctrl + C to exit app. Memif receive mode: interrupt.
-[icmpr-epoll](../examples/icmp_responder-epoll/main.c) (run in container by default) | Supports multiple connections and master mode. User can create/delete connections, set ip addresses, print connection information. [Example setup](ExampleSetup.md) contains instructions on basic connection use cases setups. Memif receive mode: interrupt. App provides functionality to disable interrupts for specified queue/s for testing purposes. Polling mode is not implemented in this example.
-[icmpr-mt](../examples/icmp_responder-mt/main.c) | Multi-thread example, very similar to icmpr-epoll. Packets are handled in threads assigned to specific queues. Slave mode only. Memif receive mode: polling (memif_rx_poll function), interrupt (memif_rx_interrupt function). Receive modes differ per queue.
diff --git a/extras/libmemif/examples/ExampleSetup.md b/extras/libmemif/examples/example_setup_doc.md
index a02506dd0ca..89a0b10e2f8 100644
--- a/extras/libmemif/examples/ExampleSetup.md
+++ b/extras/libmemif/examples/example_setup_doc.md
@@ -1,11 +1,12 @@
-## Example setup
+## Example setup    {#libmemif_example_setup_doc}
 
 #### VPP-memif master icmp_responder slave
 
-> Libmemif example app(s) use memif default socket file: /run/vpp/memif.sock.
+> Libmemif example app(s) use memif default socket file: `/run/vpp/memif.sock`.
 
 Run VPP and icmpr-epoll example (default example when running in container).
-> Other examples work similar to icmpr-epoll. Brief explanation can be found in [Examples readme](README.md) file.
+
+> Other examples work similar to icmpr-epoll. Brief explanation can be found in @ref libmemif_examples_doc .
 
 VPP-side config:
 ```
diff --git a/extras/libmemif/examples/examples_doc.md b/extras/libmemif/examples/examples_doc.md
new file mode 100644
index 00000000000..11937c576fb
--- /dev/null
+++ b/extras/libmemif/examples/examples_doc.md
@@ -0,0 +1,18 @@
+## Examples    {#libmemif_examples_doc}
+
+After build, root folder will contain scripts linking binary examples with library (same name as example apps). These scripts can be executed to run example apps without installing the library. Example apps binaries can be found in _libs_ filder. To run binaries directly, make sure that libmemif library is installed.
+
+#### Run in container
+
+`ligato/libmemif-sample-service` image contains built and installed libmemf. To run different examples, override docker CMD to start container in bash:
+
+```
+# docker run -it --entrypoint=/bin/bash -i --rm --name icmp-responder --hostname icmp-responder --privileged -v "/run/vpp/:/run/vpp/" ligato/libmemif-sample-service
+```
+Current WORKDIR is set to root repository directory. Example apps can be run from this directory (a script linking binary with library), or browse to `./.libs` folder and execute binary directly.
+
+Example app | Description
+------------|------------
+@ref extras/libmemif/examples/icmp_responder | Simplest implementaion. Event polling is handled by libmemif. Single memif conenction in slave mode is created (id 0). Use Ctrl + C to exit app. Memif receive mode: interrupt.
+@ref extras/libmemif/examples/icmp_responder-epoll (run in container by default) | Supports multiple connections and master mode. User can create/delete connections, set ip addresses, print connection information. @ref libmemif_example_setup_doc contains instructions on basic connection use cases setups. Memif receive mode: interrupt. App provides functionality to disable interrupts for specified queue/s for testing purposes. Polling mode is not implemented in this example.
+@ref extras/libmemif/examples/icmp_responder-mt) | Multi-thread example, very similar to icmpr-epoll. Packets are handled in threads assigned to specific queues. Slave mode only. Memif receive mode: polling (memif_rx_poll function), interrupt (memif_rx_interrupt function). Receive modes differ per queue.
diff --git a/extras/libmemif/README.md b/extras/libmemif/libmemif_doc.md
index 0cccfb373b5..fb4a18aff1b 100644
--- a/extras/libmemif/README.md
+++ b/extras/libmemif/libmemif_doc.md
@@ -1,5 +1,6 @@
-Shared Memory Packet Interface (memif) Library
+Shared Memory Packet Interface (memif) Library    {#libmemif_doc}
 ==============================================
+
 ## Introduction
 
 Shared memory packet interface (memif) provides high performance packet transmit and receive between user application and Vector Packet Processing (VPP) or multiple user applications. Using libmemif, user application can create shared memory interface in master or slave mode and connect to VPP or another application using libmemif. Once the connection is established, user application can receive or transmit packets using libmemif API.
@@ -63,10 +64,11 @@ commands:
 	rx-mode <index> <qid> <polling|interrupt> - set queue rx mode
 ```
 
-Continue with [Example setup](examples/ExampleSetup.md) which contains instructions on how to set up conenction between icmpr-epoll example app and VPP-memif.
+Continue with @ref libmemif_example_setup which contains instructions on how to set up conenction between icmpr-epoll example app and VPP-memif.
 
 #### Next steps
 
-- [Build instructions](docs/BuildInstructions.md) Instructions on how to build/install libmemif.
-- [Examples](examples/README.md) More example apps presenting different features.
-- [Getting started](docs/GettingStarted.md) Introduction to libmemif API. Explaining library usage in custom app.
+- @subpage libmemif_build_doc
+- @subpage libmemif_examples_doc
+- @subpage libmemif_example_setup_doc
+- @subpage libmemif_gettingstarted_doc