Code of Conduct

The membership of the ToIP Foundation pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

The Steering Committee is committed to upholding the ToIP Code of Conduct and contributors agree to act according to a standard set of behaviors that contribute to a positive environment.

Contributor's Guide

This document provides instructions for developing documentation and specifications using the ToIP MkDocs Material Theme.

Audience

These instructions are pertinent to all ToIP contributors that seek to provide content towards the objective of this ToIP deliverable. Contributors may fall into one of the following categories:

| Role | Activities | | --- | --- | | Content Author | Use an editor of choice to write sections of the target deliverable using Markdown files as fragments of the ultimate deliverable document or specification. | | GitHub skilled developer | Github savvy contributor that collects Markdown files from other contributors and manages commits and pull-requests as a representative of the team of contributors/ | | Both | Provider of content and manager of Github interactions. |

Preparation

Education

• Markdown Tutorial
• Markdown Documentation
  • Getting Started with Markdown
  • Markdwon Basics
  • Mastering the Markdown Language

Authoring Tools

• Markdown Converters for Word Processors
  • MS-Word to Markdown
    • Word-to-Markdown
    • Writage
    • How to convert Word Docs to Markdown
  • Google Docs to Markdown
    • G-Suite Plugins
    • How to convert Google Docs to Markdown
• Integrated development environment (IDE)
  • Visual Studio
  • Atom

Setup Authoring Environment

If you are a Content Author and will not work with git or do local testing of the content you are contributing, you can IGNORE these setup instructions. However, you will need to coordinate with a fellow contributor who will incorporate your work for you.

Install Dependencies

| Required Software | MacOS Installation Instructions | Windows Installation Instructions | | --- | --- | --- | | Docker | Docker Desktop| Docker Desktop| | make | Type xcode-select --install in a terminal window.|Install Chocolatey Package Installer, then install make via choco| | git | Type xcode-select --install in a terminal window OR Git Installer | Git Installer|

Understanding Development Process

This repo leverages standard pull-request code collaboration processing. Contributors to this repo should create a fork and then use that fork as the originfor their local machine based development environment.

Learn more about GitHub Forks.

Deployment

This repository contains a GitHub Action workflow that will automatically deploy your generated content when you commit your changes to:

https://trustoverip.github.io/<repository_name>

When you're forking this repository, you may need to activate GitHub Actions for your fork, as GitHub disables them by default. This is as easy as clicking on Actions in the top bar of your repository and clicking the button that is shown. If no button is shown, you're good to go.

Local Development Process

This repository uses simple make commands to manage the building and testing of content for this repo.

Open a Terminal Window and enter this command:

$ make

Prepare Development Environment

1. Clone repository

   cd <path>/<target_work_folder> git clone REPO_LINK git remote

2. Setup Environment Now we will establish your upstream connections and build the necessary Docker containers for our development environment.

$ make setup

Develop content

Optional: You can skip these steps and jump to iterative development and testing.

1. Launch the development environment

$ make devenv $bash$

Your terminal prompt will now be within the docker container environment.

1. Iteratively develop documentation content by editing the markdown files and repeating the following command which will generate static HTML content and show any errors/warnings you may want to resolve.

$bash$ make dev

1. Exit the development environment (container)

$bash$ exit $

Iterative development and testing

1. Launch the development environment

$ make devenv $bash$

Your terminal prompt will now be within the docker container environment.

1. Launch the Test Server

$bash$ make test

1. Iteratively develop documentation content by editing the markdown files. Each time you save a file, the test server will automatically refresh content for your review using your web browser pointed at: localhost. See your Makefile for actual PORT number.

2. Exit the Develop and Test environment (container)

``` Enter <control-c> to halt the test server

$bash$ exit $ ```

Generate HTML and PDF Docs

This repo will combine all contributed content into a single Markdown file which is then used to produce standalone HTML and PDF files. Internal scripts will preprocess and concatenate all Markdown files in the order specified in mkdocs.yml. The scripts will ensure that internal links to pages and anchors are correct.

1. Launch the Publish Environment

$ make pubenv $bash$

Your terminal prompt will now be within the docker container environment.

1. Run the publishing process which will generate various versions of the contnet in the ./publish folder.

$bash$ make publish

1. Exit the publishing environment (container)

``` Enter <control-c> to halt the test server

$bash$ exit $ ```

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, ensure your fork and local-machine are in sync with changes made to the upstream repo.

$ make rebase

ToIP <TypeIndicator><4digitID>: <DeliverableName>

Update title. For example, BP000: Utility Selection Criteria DELETE THIS COMMENT

• Authors: your name -- email is optional
• Status: PROPOSED
• Since: YYYY-MM-DD (date you submit your PR)
• Status Note: (explanation of current status)
• Supersedes: (link to anything this ToIP Deliverable supersedes)
• Start Date: YYYY-MM-DD (date you started working on this idea)
• Tags: (see Tag Options

Summary

One paragraph explanation of the objective of the subject ToIP deliverable. DELETE THIS COMMENT

Purpose

This repo manages the development and maintenance of the subject ToIP deliverable. It contains the tools necessary to generate multiple renderings formats.

1. Interactive Online Website: GitHub Pages
2. Printable Documents
   • PDF Version
   • HTML Version
   • Standalone Markdown

Contributor's Guide

Documentation and Specification contributors should familiarize themselves with the Authoring Process. Replace <REPO_NAME>

Related Resources

1. ToIP Deliverables Portal - Status
2. ToIP Contributor's Workflow

Requirements

Workflow

ToIP contributors should be able to: 1. Gather: Define, Organize and Assign work towards the development of a ToIP Deliverable based on project outline that aggregates a collection of discrete Markdown files. 2. Author: Use any Markdown editor they desire. 3. Produce: Configure the generation of one or two possible deliverables: General Document, Specification.

Styling

1. Apply a Material style Theme that is ToIP specific
2. Leverage a Color pallet derives from the ToIP Logo Assets.
3. Provide configurable navigator with numeric outlines level 1-3: See Spec-Up as an example style for the development of specifications.
4. Build upon the Material Theme (not insiders) with Search Suggest and/or Highlight - void of Insider Token requirements.
5. One ToIP Theme with config option for header generated numbering (with or without).

Versioning

ToIP members should be able to prime to repos using this repo as a GitHub Template Repository.

Development and Processing

1. Command line tools (make) for generating local test content.
2. Github workflow (actions) for producing GitHub-Pages
3. Layout (outline / organize) multiple markdown files (i.e.: mkdocs.yml)

Rendering Formats

Minimally, this repo MUST allow for the configuration of generating these rendering formats: 1. Single Markdown file (via pandoc or other plugins) 2. Single PDF (via pdf-export or other plugins) 3. Website/GitHub-Pages