dgerod / sgb-tw

A tool to write a Software Guidebook using wiki syntax, PlantUML, etc. and TiddlyWiki as GUI

SGB-TW

What is this?

A tool that helps you to write your Software Guidebook (SGB) using wiki syntax, PlantUML, etc. and TiddlyWiki (TW) as GUI. An example of how to use this tool is here.

What is a Software Guide-Book?

It is a document describes the software architecture and high-level design of a system. In addition to that, the document contains maps, sight and itineraries, history and culture and practical information about the software; it describes what the code does not. And it is an alive and evolve document.

Understanding the SGB-TW tool

Installation

1. Create a Python virtual environment.

   • Using Conda, for more information see this.

     $ conda create --name sgb python=3.7

   • Using venv, for more information see this.

     $ python3 -m sgb /path/to/new/virtual/environment

2. Activate the virtual environment

3. Install Python requirements by calling:

   $ pip install -r requirements.txt

4. Install Timini to be able to save the TiddlyWiki file from your web-browser.

Steps (1) and (2) are not mandatory but recomended, using virtual environments avoid mixing required packages of this application with your Python environment.

How to use

Activate the virtual environment. For example using conda:

$ conda activate sgb

Open TiddlyWiki HTML page in your web browse.

Start your daily work by opening TiddlyWiki HTML page in your web browse. After that synchronize TiddlyWiki with your tiddlers in the DB by executing:

$ git pull
$ python sgb-cli.py load_tiddlers

The sadac-cli command loads tiddlers from DB and add to TiddlyWiki file. Once this is done you have to reload the TiddlyWiki page in your web browser..

Once you whant to want to store the tiddlers in the DB, for doing that you have to execute:

$ python sgb-cli.py save_tiddlers
$ git push

In case that there is a conflict in git, you should load the tiddlers to the TiddlyWiki HTML file after solving it.

sgb-tw's Issues

Generate SGB report in PDF

Add detailed explanation about how add notes

Create another repository with example of sgb

Add a user command to create a new SGB

Custom style in note type tiddlers

Using styles it is possible to add an empty line between paragraph, and this makes a tiddler easy to read when there is a lot of information.

Add button to add help and structure tiddlers

Allow to have DB in outside the tool

Make PlantUML include macro work

Add ADR button that creates tiddler based on template

Tiddlers in DB stored in directories

• Store tiddlers directories in DB, one directory per letter so tiddlers starting by "a" will be stored in "a" directory. In this way we don't have a lot of tiddlers in the same directory
• Change extension of tiddlers from .cotent to .tid, so we use the "standard" name.

Add slides explaining concept and how to use

Backup TW html base after modifying tiddlers that are defining structure