/spec-up

Create beautiful, feature-rich technical specifications in markdown

Primary LanguageHTMLMIT LicenseMIT

Trust over IP - 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 Spec-Up for the development of ToIP Deliverables.

The ToIP Spec-Up Theme is a ready-to-use customized version of Spec-Up that provides a ToIP branded environment for the development of technical specifications.

Markdown » Spec-Up

Spec-Up is a technical specification development tool that enables you to create rich specification documents for standards bodies and engineering projects by writing in an extended version of markdown that features all the bells and whistles - for example: advanced syntax highlighting, notice blocks, complex tables, charts, UML diagrams, and more.

Purpose

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

Acknowledgements

This repo is derived from the fine work of Daniel Buchner and his Spec Generator with Express enhancements suggested by Daniel N. Gisolfi.

Contributor's Guide

Once the new repo instance has been configured, 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 the trustoverip/spec-up GitHub Repo Template.

Prime and clone a new repository

  1. Generate a new repository from this template repository (see GitHub docs).
  2. 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 contributors should consider using the ToIP themed repo for MkDocs Material.

Configure Spec-Up

In addition to the following instructions, please refer to the Spec-Up Getting Started Guide.

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

  2. Edit the specs.json file.

  3. Review the specs[] array. By default, this arrays contains three (3) samples:

    1. Spec-Up Standalone Example: Demonstration of how to use Spec-Up with a single standalone Markdown file, called spec.md.
    2. Spec-Up Multi-File Example: Demonstration of how to use Spec-Up with an array of Markdown files.
    3. ToIP TSS0000 SpecName: A placeholder for a new ToIP Spec.

  4. Modify the specs[] array, using a combination of options:

    1. Remove the Examples
    2. Keep the Examples
    3. Modify the TSS0000 entry
    4. Extend the array with another entry, as this repo can be used to serve more than one specification. This may be appropriate when a single TSS requires related or dependency specifications.

Configure Express Server

This Spec-Up repo uses a Node Express Server to server the web-application.

  1. Open the repository using your favorite IDE (i.e. Visual Studio Code, Atom).
  2. Edit the server.js file.
  3. Update the redirect and web-site path information according to the specifications that will be hosted (as defined in specs.json). For indepth details on configuring an Express Server, please refer to the Express API.

Configure Makefile

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

  2. Edit the Makefile file and find the variables depicted below:

    REPO_NAME ?= TSS0000-some-new-spec
UPSTREAM_REPO ?= https://github.com/trustoverip/TSS0000-some-new-spec.git
DEV_SITE_PORT ?= 7600
SITE_DIR ?= spec_site/toip

  3. 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
    4. SITE_DIR: Use default or change relative path name for where the Markdown files for this new specification will be stored.

Update Readme

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

  2. 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.

  3. Move README.md to the archive folder. Rename it to ORIGINAL_INSTRUCTIONS.md.

  4. Rename DOC_README.md to README.md

  5. 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.