white-paper

Manage the development and maintenance of the Foundation level white paper. This paper focuses on how the Foundation is organized and what it will deliver.

This repo contains the content resources for the generation of a white paper deliverable. It contains the tools necessary to generate two document renderings (printed, online).

Contents

1. Online White Paper Access
   • GitHub Pages
   • Trust over IP Website FIX LINK
2. Printable White Paper (PDF Version)

Dependencies

• MkDocs
• PDF Generation
  • WeasyPrint
  • MkDocs PDF Export Plugin

Documentation Development Process

The ToIP Foundation leverages uses standard pull-request code collaboration processing. Contributors to this repo should create a fork and then use that fork as the origin for their local machine based development.

Local Development Process

This repo uses GitHub Pages to host the static HTML content that is generated by MkDocs. The gh-pages branch reflects the latest committed docs. See make pages.

Use make to manage the build process for this repo.

$ make

Prepare Development Environment (MacOS)

1. Clone repository

git clone git@github.com:trustoverip/white-paper.git
git remote
git remote add upstream git@github.com:trustoverip/white-paper.git
git remote

2. Setup Environment

$ make setup

Develop content

Iteratively develop documentation content using markdown files.

$ make dev

Test content

Iteratively review online content using localhost.

$ make test

Generate HTML and PDF Docs

This repo uses mkdocs gh-deploy to push generated HTML content to the gh-pages branch on the origin repo on GitHub. This process also creates a single PDF document in the pdf folder but the file is not pushed.

$ make pages

Note: You can ignore the DEBUG and WARNING messages during the PDF generation.

Commit Code

To complete the development process, follow normal git commit and git push processing. The .gitignore file will prevent the pushing of the static HTML content.

Resync with Upstream

Before each coding session, insure your fork and local-machine are in sync with changes made to the upstream repo.

make rebase

Upstream Refresh Process

This repo uses a GitHub Workflow process coupled with a GitHub Action to automatically refresh the GitHub Pages on the upstream repo.

Help

Please refer to mkdocs-pdf-export-plugin for PDF tooling configuration help.