docs: Add manpage to mkdocs

Uses pandoc to convert the manpage into a markdown document and add it
to the mkdocs documentation.

Signed-off-by: Maximilian Nitsch <maximilian.nitsch@d3tn.com>

Makefile

@@ -52,12 +52,16 @@ storage-agent-proto-headers:
 # Docs
 ###############################################################################
 
+.PHONY: pandoc-gen-doc
+pandoc-gen-doc:
+	pandoc --from man --to gfm+definition_lists --shift-heading-level-by 1 --output doc/references/manpage.md doc/ud3tn.1
+
 .PHONY: protoc-gen-doc
 protoc-gen-doc:
 	protoc --doc_out=doc/references/protobuf --doc_opt=doc/references/protobuf/protoc-gen-doc-markdown.tmpl,index.md components/aap2/aap2.proto components/agents/storage/storage_agent.proto
 
 .PHONY: doc
-doc: protoc-gen-doc
+doc: pandoc-gen-doc protoc-gen-doc
 	mkdocs build --site-dir result/
 
 ###############################################################################

doc/README.md

@@ -8,6 +8,7 @@ An HTML version of the μD3TN documentation is created via [MkDocs](https://www.
 
 - w/o nix
 
+  - Install [pandoc](https://pandoc.org/installing.html)
   - Install [protoc](https://grpc.io/docs/protoc-installation/)
   - Install [protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc) via your package manager, `go install` or another preferred method
 
@@ -34,6 +35,13 @@ An HTML version of the μD3TN documentation is created via [MkDocs](https://www.
 ### Develop
 
 ```sh
+# create markdown docs from manpage
+pandoc \
+  --from man \
+  --to gfm+definition_lists \
+  --shift-heading-level-by 1 \
+  --output doc/references/manpage.md \
+  doc/ud3tn.1
 # Create markdown docs from protobuf
 protoc \
   --doc_out=doc/references/protobuf \

doc/references/.gitignore

@@ -0,0 +1 @@
+manpage.md

mkdocs.yaml

@@ -117,7 +117,7 @@ nav:
     - pyd3tn API Reference: 'references/pyd3tn.md'
     - Protobuf: 'references/protobuf/index.md'
     # - Configurations:
-    # - Manpages:
+    - Manpages: 'references/manpage.md'
     - Research Papers: 'references/papers.md'
     # - Projects:
 

nix/packages.nix

@@ -68,6 +68,7 @@ rec {
 
     nativeBuildInputs = with pkgs; [
       doxygen
+      pandoc
       protobuf
       protoc-gen-doc
     ] ++ (with python3Packages; [
@@ -84,7 +85,12 @@ rec {
         --doc_opt=doc/references/protobuf/protoc-gen-doc-markdown.tmpl,index.md \
         components/aap2/*.proto \
         components/agents/storage/storage_agent.proto
-
+      pandoc \
+        --from man \
+        --to gfm+definition_lists \
+        --shift-heading-level-by=1 \
+        --output doc/references/manpage.md \
+        doc/ud3tn.1
       mkdocs build --site-dir $out
     '';
   };

nix/shell.nix

@@ -30,6 +30,7 @@ pkgs.mkShell rec {
     jansson
     llvmPackages.libcxxClang
     nixpkgs-fmt
+    pandoc
     protobuf
     protoc-gen-doc
     python3Packages.flake8