ud3tn/doc

Documentation

MkDocs

An HTML version of the μD3TN documentation is created via MkDocs. All files stored in the MkDocs directory are taken into account. The MkDocs configuration can be changed in the mkdocs.yaml file. To add further pages to the navigation, they must be added to the nav section.

Prepare

• w/o nix

  • Install pandoc

  • Install protoc

  • Install protoc-gen-doc via your package manager, go install or another preferred method

    To install it as an unprivileged user in a subdirectory of the work tree:

    GOBIN=$(pwd)/.gobin/ go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@latest
    # Then, run all protoc commands as follows:
    PATH=$(pwd)/.gobin/:$PATH protoc ...
    

  • Install mkdocs and relevant Python dependencies (preferably use a virtual environment)

    pip install -U mkdocs
    pip install $(mkdocs get-deps)
    

• w/ nix (see also the µD3TN documentation on it)

  nix develop '.?submodules=1'
  

Develop

# 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_opt=markdown,index.md \
  components/aap2/aap2.proto \
  components/agents/storage/storage_agent.proto
# Run dev-server for live preview of HTML documents (without protobuf)
mkdocs serve

Build

# w/o nix
make doc

# w/ nix
nix build .#mkdocs-html

Deploy

When changes are made to the master branch, the latest version of the documentation is automatically built and published at https://d3tn.gitlab.io/ud3tn.

Man Page

There exists also a man page for μD3TN, which can be viewed with

man --local-file ud3tn.1