Merge pull request #4461 from vgteam/docmd

Add man page

Brewfile

@@ -20,3 +20,4 @@ brew "autoconf"
 brew "cmake"
 brew "boost"
 brew "pybind11"
+brew "pandoc"

Dockerfile

@@ -44,7 +44,7 @@ RUN apt-get -qq -y update && apt-get -qq -y upgrade && apt-get -qq -y install \
     samtools curl unzip redland-utils librdf-dev cmake pkg-config wget gtk-doc-tools \
     raptor2-utils rasqal-utils bison flex gawk libgoogle-perftools-dev liblz4-dev liblzma-dev \
     libcairo2-dev libpixman-1-dev libffi-dev libcairo-dev libprotobuf-dev libboost-all-dev \
-    tabix bcftools libzstd-dev pybind11-dev python3-pybind11
+    tabix bcftools libzstd-dev pybind11-dev python3-pybind11 pandoc
 ###DEPS_END###
 
 # Prepare to build submodule dependencies

Makefile

@@ -544,10 +544,17 @@ docs: $(SRC_DIR)/*.cpp $(SRC_DIR)/*.hpp $(ALGORITHMS_SRC_DIR)/*.cpp $(ALGORITHMS
 	doxygen
 	echo "View documentation at: file://$(PWD)/doc/doxygen/index.html"
 
-man: $(patsubst doc/asciidoc/man/%.adoc,doc/man/%.1,$(wildcard doc/asciidoc/man/*.adoc))
+man: doc/wiki/vg-manpage.md doc/man/vg.1
 
-doc/man/%.1: doc/asciidoc/man/%.adoc
-	asciidoctor -b manpage -d manpage -o $@ $<
+#The manpage markdown has an extra line needed for the actual manpage format
+doc/man/vg-manpage.md: $(BIN_DIR)/$(EXE) doc/vgmanmd.desc.md doc/vgmanmd.py
+	mkdir -p doc/man && ./doc/vgmanmd.py > $@.tmp && mv $@.tmp $@
+
+doc/wiki/vg-manpage.md: doc/man/vg-manpage.md
+	sed 1d doc/man/vg-manpage.md > $@
+
+doc/man/vg.1: doc/man/vg-manpage.md
+	pandoc --standalone --to man $< -o $@
 
 # Hack to use gshuf or shuf as appropriate to the platform when testing
 $(BIN_DIR)/shuf:

README.md

@@ -2,7 +2,8 @@
 # vg
 
 [![Join the chat at https://gitter.im/vgteam/vg](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/vgteam/vg?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Latest Release](https://img.shields.io/github/release/vgteam/vg.svg)](https://github.com/vgteam/vg/releases/latest) 
-[![Doxygen API Documentation](https://img.shields.io/badge/doxygen-docs-brightgreen.svg)](https://vgteam.github.io/vg/)
+[![Doxygen API Documentation](https://img.shields.io/badge/doxygen-docs-firebrick.svg)](https://vgteam.github.io/vg/)
+[![vg man page](https://img.shields.io/badge/manpage-seagreen.svg)](https://github.com/vgteam/vg/wiki/vg-manpage)
 
 ## variation graph data structures, interchange formats, alignment, genotyping, and variant calling methods
 
@@ -501,6 +502,8 @@ Most commands allow the streaming of graphs into and out of `vg`.
 
 ### Command line interface
 
+See the [man-page](https://github.com/vgteam/vg/wiki/vg-manpage)
+
 A variety of commands are available:
 
 - *autoindex*: construct graphs and indexes for other tools from common interchange file formats

doc/README.md

@@ -0,0 +1,25 @@
+# Automated markdown manpage
+
+Make a markdown document with the usage messages of (selected) `vg` subcommands. 
+Calls the `vg` command, so it will match the version available in the command line.
+
+```sh
+python3 vgmanmd.py > wiki/vg-manpage.md
+```
+
+Then commit and push the changes to the wiki submodule, or copy the markdown content to the [wiki page](https://github.com/vgteam/vg/wiki/vg-manpage).
+
+## Edit descriptions
+
+See [`vgmanmd.desc.md`](vgmanmd.desc.md) file. 
+This file must be in the current directory. 
+Also, in the title `# <NAME>`, `<NAME>` should match name of the command. 
+The name `intro` is used for the introduction, to be placed after the table of content.
+The names don't need to match a command, and not all commands have to be described: if available, a subcommand description will be added before its usage message.
+
+The goal of the description is to be vague enough that we don't need to change them often, but informative enough that new users can get a good feel of the commands, plus pointers to other resources (e.g. Wiki pages).
+
+## Change list of selected subcommands
+
+At the top of [`vgmanmd.py`](vgmanmd.py), change the *cmds* list.
+