https://github.com/ericsson/specpress
https://github.com/ericsson/specpress
Last synced: 8 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/ericsson/specpress
- Owner: Ericsson
- License: mit
- Created: 2025-04-22T15:04:33.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-04-30T13:17:00.000Z (9 months ago)
- Last Synced: 2025-05-07T18:15:53.435Z (8 months ago)
- Language: JavaScript
- Size: 59.6 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SpecPress
Export PDF and/or DOCX files from a subset of Markdown, ASN.1 and JSON files.
## System Requirements
SpecPress requires the following software to be installed on your system:
- [Git](https://git-scm.com/)
- [Node.js version 20+](https://nodejs.org/en)
- [OpenJDK](https://openjdk.org/)
Additionally, if you eould like to use pandoc to convert mardown files into pdf or docx documents you need to install also:
- [pandoc](https://pandoc.org/installing.html) by [John MacFarlane](https://johnmacfarlane.net/)
- [MiKTeX](https://miktex.org/download) or [TeX Live](https://tug.org/texlive/) which include `pdflatex`
## Getting started
### Initialize your project
Create a folder for your specification, move into the folder and initialize `npm` by running the following commands in the terminal:
```
# create a new folder called for example "ts101"
mkdir ts101
# move into the folder
cd ts101
# initialize npm
npm init
```
### Install SpecPress
Install specpress as a development dependency of your project and initialize it with the following commands:
```
# install specpress
npm install specpress --save-dev
# initialize specpress
npx sp_init
```
#### /ts101/src folder
As part of its initialization sprecpress created the `src` folder in the projec’s root folder `ts101`. Use the `src` folder to store all your specifications files, i.e., the: `.md, .json, .asn, .txt` files. Within the `src` folder you can create whatever structure of subfolder you like. You could also consider cloning a git repository containing you specification files under the `src` folder.
If you want, you can rename the `src` folder to whatever name you like. Should you do so, you should also update the value of the `sourceFolderName` parameter in the `sp.config.json` file accordantly, e.g., `”sourceFolderName”: “yourPreferedName”`.
#### /ts101/sp.config.json file
The initialization process also publishes a configuration files `sp.config.json` in the root folder `/ts101/sp.config.json`.
```
#./sp.config.json
{
"pathFiguresFolder": "/assets/figures",
"sourceFolderName": "src"
}
```
Along with the `"sourceFolderName": "src"` parameter, this files contains the `”pathFiguresFolder": "/assets/figures"` parameter which indicates the `src` subfolder where specpress will save the `.png` files it generates for the UML sequence diagrams. The default values is `/assets/figures` so the files will be saved in the `/ts101/src/assets/figures` folder. Before going any further, please make sure to set the value of `pathFiguresFolder` so that it points to the right `src` subfolder in your folder structure.
`
## Usage
Move now into your working directory which can be the `src` folder or a subfolder of `src`.
In the working folder you can use the following specpress commands in the terminal:
### Export a .docx|.html|.pdf file
Specpress enables you to export a file which contains all the specification files from the working folder. The exported file will be saved in the `/ts101/export` folder.
```
# export a pdf file
npx sp_export pdf
# export a docx file
npx sp_export docx
# export a html file
npx sp_export html
# export a pdf file using pandoc
npx sp_export pdf pandoc
# export a docx file using pandoc
npx sp_export docx pandoc
# export a html file using
npx sp_export html pandoc
```
### Generate UML diagrams from text files using PlantUML
Specpress enables you to automatically generate `.png` files containing UML diagrams using as an input a text file containing a textual description of the UML diagram as presented in the example below:
```
#/ts101/src/example.txt
@startuml
Alice -> Bob: Authentication Request
Boby --> Alice: Authentication Response
@enduml
```
The `.png` files are saved in the src subfolder indicated in the `sp.config.json` files.
```
# generale .png files for all the .txt files in the working folder
npx sp_generateUML
# generale .png file for a specific .txt file in the working folder
npx sp_generateUML-file ./example.txt
```
### Display the specification as a web page
Execute the following commands to display your specification as a webpage on your local http server:
```
#create the /ts101/public/index.html file
npx sp_publish
# start the http server from the /ts101/public folder
# the server is accessible at http://lcalhost:8080
npx sp_serve
```
### Watch for changes in your source files
```
npx sp_watch
```
The `sp_watch` command will:
- watch for changes in your specification’s source files `[".asn", ".json", ".md"]` and update the `index.html` file according to your changes,
- watch for changes in your UML sequence diagrams source files `[".puml", ".txt"]` and generate the corresponding PNG files in the `/ts101/src/assets/figures` folder
### Start working on your specification
```
npx sp_start
```
The `sp_strat` command is equivalent to running the `sp_pubish`, `sp_watch` and `sp_serve` commands at once.
## Repository
[https://github.com/Ericsson/specpres](https://github.com/Ericsson/specpress)