Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add man page #4461

Open
wants to merge 15 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Brewfile
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,4 @@ brew "autoconf"
brew "cmake"
brew "boost"
brew "pybind11"
brew "pandoc"
2 changes: 1 addition & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
13 changes: 10 additions & 3 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
25 changes: 25 additions & 0 deletions doc/README.md
Original file line number Diff line number Diff line change
@@ -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.

203 changes: 0 additions & 203 deletions doc/asciidoc/man/vg-giraffe.adoc

This file was deleted.

Loading
Loading