Trust over IP - Documentation and Specification Template

This repo is a GitHub Repo Template for creating GitHub repositories within the ToIP GitHub Organization. Newly generated repos will contain all the necessary code for using MkDocs for the development of ToIP Deliverables.

The ToIP MkDocs Material Theme a ready-to-use setup for a ToIP branded version of MkDocs, a static site generator geared towards (technical) project documentation and specification development. The theme is a customized version of Material for MkDocs.

Purpose

This repo has been developed to address the requirements of ToIP Foundation contributors with respect to the authoring process for ToIP Deliverables.

Contributor's Guide

Once the new repo instance has been configured, Documentation and Specification contributors should familiarize themselves with the Contributor's Guide.

Usage

The following instructions pertain to the initial configuration of a new repository instance that has been primed using trustoverip/mkdocs-material GitHub Repo Template.

Prime and clone a new repository

Generate a new repository from this template repository (see GitHub docs).
Clone the new repository (see GitHub docs).

Pick a theme style

This repo supports the use of a Specification styled theme when the ToIP Deliverable Type Indicator is TSS. In all other cases, a General Documentation styled theme is provided.

Open the repository using your favorite IDE (i.e. Visual Studio Code, Atom).
Apply your style selection

Style	Configuration Action	View Demo
General Documentation	Move the `mkdocs.spec.yml` file, which is located at the root of the repo, to the `archive` folder.	ToIP MkDocs Theme for Documentation
Specification	Move the `mkdocs.yml` file to the `archive` folder, and rename `mkdocs.spec.yml` to `mkdocs.yml`.	ToIP MkDocs Theme for Specs

Configure MkDocs

MkDocs uses a YAML file to configure the operational properties for the document generator.

Open the repository using your favorite IDE (i.e. Visual Studio Code, Atom).

Edit the mkdocs.yml file and find the sections depicted below:

# Project information
site_name: Trust over IP – General Template
site_url: https://trustoverip.github.io/mkdocs-material/
site_author: Jane Doe
site_description: >-
  Trust over IP Foundation template for general documentation
  and technical specification using Material for MkDocs

# Repository information
repo_name: trustoverip/mkdocs-material
repo_url: https://github.com/trustoverip/mkdocs-material

# Content Generator Settings
docs_dir: 'content'
site_dir: 'html'

Update the following settings:
1. site_name: Set to ToIP Deliverables name using the naming convention <TypeIndicator><4digitID>: <DeliverableName>. For example, BP000: Utility Selection Criteria.
2. site_url: Set to the GitHub Pages URL that will serve up this new repo site.
3. site_author: Set to the sponsoring ToIP WG. For example, ToIP Governance Stack WG.
4. site_description: Set to a short description of the ToIP Deliverable being documented by this repo.
5. repo_name: Set using name of the new GitHub repo.
6. repo_url: Set using the URL of the new GitHub repo.
7. docs_dir: Enter the preferred directory name for where the content for this document/spec will reside.
8. site_dir: Enter the preferred directory name for where the static HTML pages will be generated from Markdown files.
9. extra.title: Set to ToIP Deliverables name using the naming convention <TypeIndicator><4digitID>: <DeliverableName>. For example, BP000: Utility Selection Criteria.

Configure Makefile

Open the repository using your favorite IDE (i.e. Visual Studio Code, Atom).

Edit the Makefile file and find the variables depicted below:

REPO_NAME ?= mkdocs-material
UPSTREAM_REPO ?= https://github.com/trustoverip/mkdocs-material.git
DEV_IMAGE ?= trustoverip/mkdocs-material-devenv
PANDOCS_IMAGE ?= trustoverip/pandocs-devenv
DEV_SITE_PORT ?= 7500
DEV_HOST_DIR ?= host_mkdocs
PUB_HOST_DIR ?= host_pandocs
PUBLISH_DIR ?= publish

Update the following settings:
1. REPO_NAME: Provide the GitHub repository name.
2. UPSTREAM_REPO: Set using the GitHub Repo Clone URL.
3. DEV_SITE_PORT: Pick a port that will be used for the local test server: https://localhost:8080

Update Readme

Open the repository using your favorite IDE (i.e. Visual Studio Code, Atom).
Based on the type of deliverable that will be associated with this new repo, copy the appropriate template from the templates folder within the trustoverip/deliverables repo to ./archive/SUGGESTED_OUTLINE.md.
Move README.md to the archive folder. Rename it to ORIGINAL_INSTRUCTIONS.md.
Rename DOC_README.md to README.md
Update README.md accordingly.
1. At the top of your file modify the title so it is in the form:
```
<TypeIndicator><4digitID>: Friendly Version of Your Title.
```
2. Refer to the Contribution Options of the ToIP Deliverables Portal.

vinomaster/toip-mkdocs-material