Add oritentation support and add more documentation.

CHANGELOG.md

@@ -1,3 +1,5 @@
+# 0.2.2 - 2022-02-27
+* support using different orientation
 # 0.2.1 - 2022-02-27
 * disable a group if all its skills are new or not specified
 # 0.2.0 - 2022-02-27

LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012-2022 Scott Chacon and others
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,207 @@
+# skillmap
+A tool for generating skill map/tree like diagram.
+
+# What is a skill map/tree?
+Skill tree is a term used in video games, and it can be used for describing roadmaps for software project development as well.
+
+This project borrows inspiration and ideas from two sources:
+1. https://hacks.mozilla.org/2018/10/webassemblys-post-mvp-future/
+2. https://github.com/nikomatsakis/skill-tree
+
+# Installation
+```
+pip install skillmap
+```
+After installation, a `skillmap` command is available.
+
+# Usage
+1. Create a toml format skill map descriptor file. You can find more details about this descriptor format [here](docs/skillmap_descriptor.md). For a minimal example, see [`docs/examples/hello_world.toml`](docs/examples/hello_world.toml)
+```
+[skillmap]
+name = "hello world"
+icon = "bicycle"
+
+[groups.learn_python]
+name = "learn python"
+icon = "rocket"
+    [groups.learn_python.skills.print]
+    name = "print statement"
+    icon = "printer"
+    [groups.learn_python.skills.string]
+    name = "string literal"
+    icon = "book"
+```
+
+2. Run `skillmap path/to/your/skillmap.toml`
+   1. For example, `skillmap docs/examples/hello_world.toml`
+3. Copy the generated skill map diagram to your clipboard.
+4. Paste the diagram to a mermaid diagram editor, for example, [`https://mermaid-js.github.io/mermaid-live-editor`](https://mermaid-js.github.io/mermaid-live-editor).
+
+# Examples
+```mermaid
+flowchart TD
+url_shortener(fa:fa-hashtag <br/>url shortener)
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+subgraph groups.webui[fa:fa-desktop web ui]
+groups.webui.skills.url_validator(fa:fa-globe <br/>url validator)
+class groups.webui.skills.url_validator newSkill;
+groups.webui.skills.react-->groups.webui.skills.url_validator
+groups.webui.skills.react(fa:fa-list <br/>react)
+class groups.webui.skills.react beingLearnedSkill;
+
+end
+class groups.webui normalSkillGroup;
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+subgraph groups.native_client[fa:fa-desktop native client]
+groups.native_client.skills.react_native(fa:fa-mobile <br/>react native)
+class groups.native_client.skills.react_native newSkill;
+
+groups.native_client.skills.other_clients(fa:fa-lock <br/>???)
+class groups.native_client.skills.other_clients unknownSkill;
+
+end
+class groups.native_client newSkillGroup;
+groups.webui-->groups.native_client
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+subgraph groups.backend[fa:fa-server backend]
+groups.backend.skills.restapi(fa:fa-send <br/>REST API)
+class groups.backend.skills.restapi learnedSkill;
+
+groups.backend.skills.database(fa:fa-database <br/>database)
+class groups.backend.skills.database learnedSkill;
+
+end
+class groups.backend normalSkillGroup;
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+subgraph groups.partitioned_backend[fa:fa-copy partitioned backend]
+groups.partitioned_backend.skills.proxy(fa:fa-anchor <br/>proxy)
+class groups.partitioned_backend.skills.proxy beingLearnedSkill;
+
+groups.partitioned_backend.skills.database(fa:fa-database <br/>partitioned database)
+class groups.partitioned_backend.skills.database beingLearnedSkill;
+
+end
+class groups.partitioned_backend normalSkillGroup;
+groups.backend-->groups.partitioned_backend
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+subgraph groups.cache[ cache]
+groups.cache.skills.memcache(fa:fa-magnet <br/>memcache)
+class groups.cache.skills.memcache learnedSkill;
+
+groups.cache.skills.redis(fa:fa-lock <br/>???)
+class groups.cache.skills.redis unknownSkill;
+
+end
+class groups.cache normalSkillGroup;
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+url_shortener-->groups.webui
+url_shortener-->groups.backend
+url_shortener-->groups.cache
+classDef normalSkillGroup stroke:#0096C7,stroke-width:4px,fill:#CAF0F8;
+
+classDef beingLearnedSkill stroke-width:2px,stroke:#90E0EF,fill:#ADE8F4;
+classDef learnedSkill stroke-width:2px,stroke:#00B4D8,fill:#48CAE4;
+
+classDef newSkillGroup stroke-width:4px,stroke:#D6CCC2,fill:#EDEDE9;
+classDef newSkill stroke-width:2px,stroke:#D6CCC2,fill:#EDEDE9;
+classDef unknownSkill stroke-width:2px,stroke:#D6CCC2,fill:#EDEDE9;
+
+class url_shortener normalSkillGroup;
+```
+
+```mermaid
+flowchart TD
+url_shortener(fa:fa-hashtag <br/>url shortener)
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+subgraph groups.webui[fa:fa-desktop web ui]
+groups.webui.skills.url_validator(fa:fa-globe <br/>url validator)
+class groups.webui.skills.url_validator newSkill;
+groups.webui.skills.react-->groups.webui.skills.url_validator
+groups.webui.skills.react(fa:fa-list <br/>react)
+class groups.webui.skills.react beingLearnedSkill;
+
+end
+class groups.webui normalSkillGroup;
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+subgraph groups.native_client[fa:fa-desktop native client]
+groups.native_client.skills.react_native(fa:fa-mobile <br/>react native)
+class groups.native_client.skills.react_native newSkill;
+
+groups.native_client.skills.other_clients(fa:fa-lock <br/>???)
+class groups.native_client.skills.other_clients unknownSkill;
+
+end
+class groups.native_client newSkillGroup;
+groups.webui-->groups.native_client
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+subgraph groups.backend[fa:fa-server backend]
+groups.backend.skills.restapi(fa:fa-send <br/>REST API)
+class groups.backend.skills.restapi learnedSkill;
+
+groups.backend.skills.database(fa:fa-database <br/>database)
+class groups.backend.skills.database learnedSkill;
+
+end
+class groups.backend normalSkillGroup;
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+subgraph groups.partitioned_backend[fa:fa-copy partitioned backend]
+groups.partitioned_backend.skills.proxy(fa:fa-anchor <br/>proxy)
+class groups.partitioned_backend.skills.proxy beingLearnedSkill;
+
+groups.partitioned_backend.skills.database(fa:fa-database <br/>partitioned database)
+class groups.partitioned_backend.skills.database beingLearnedSkill;
+
+end
+class groups.partitioned_backend normalSkillGroup;
+groups.backend-->groups.partitioned_backend
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+subgraph groups.cache[ cache]
+groups.cache.skills.memcache(fa:fa-magnet <br/>memcache)
+class groups.cache.skills.memcache learnedSkill;
+
+groups.cache.skills.redis(fa:fa-lock <br/>???)
+class groups.cache.skills.redis unknownSkill;
+
+end
+class groups.cache normalSkillGroup;
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+url_shortener-->groups.webui
+url_shortener-->groups.backend
+url_shortener-->groups.cache
+classDef normalSkillGroup stroke-width:4px,stroke:#DCEBCA,fill:#E9F5DB;
+classDef beingLearnedSkill stroke-width:2px,stroke:#C2D5AA,fill:#CFE1B9;
+classDef learnedSkill stroke-width:2px,stroke:#A6B98B,fill:#B5C99A;
+
+classDef newSkillGroup stroke-width:4px,stroke:#D6CCC2,fill:#EDEDE9;
+classDef newSkill stroke-width:2px,stroke:#D6CCC2,fill:#EDEDE9;
+classDef unknownSkill stroke-width:2px,stroke:#D6CCC2,fill:#EDEDE9;
+
+%% https://www.w3schools.com/colors/colors_groups.asp
+linkStyle default stroke-width:2px,stroke:OliveDrab;
+class url_shortener normalSkillGroup;
+```
+
+# License
+[MIT License](LICENSE)
+
+# More details
+* Skillmap toml descriptor format can be found [here](docs/skillmap_descriptor.md)
+* hot reloading when authoring a skillmap toml file
+    * install several tools to make hot reloading to work
+        * [`entr`](https://github.com/eradman/entr), run arbitrary commands when files change
+        * [Visual Studio Code](https://code.visualstudio.com) + [Markdown Preview Enhanced Visual Studio Code Extension](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced)
+        * Basically, use `entr` to watch toml file changes, and generate a `md` makrdown file using `skillmap` every time when toml file changes. And use `vscode` + `Markdown Preview Enhanced` extension to open this generated markdown file. Check out `build_sample` and `dev_sample` in [justfile](justfile) to see how to make hot reloading work

docs/examples/hello_world.toml

@@ -0,0 +1,13 @@
+[skillmap]
+name = "hello world"
+icon = "bicycle"
+
+[groups.learn_python]
+name = "learn python"
+icon = "rocket"
+    [groups.learn_python.skills.print]
+    name = "print statement"
+    icon = "printer"
+    [groups.learn_python.skills.string]
+    name = "string literal"
+    icon = "book"

docs/skillmap_descriptor.md

@@ -0,0 +1,52 @@
+# Skillmap descriptor format
+* The skillmap descriptor format is a toml file. Here is a minimal example, see [`examples/hello_world.toml`](examples/hello_world.toml)
+* It describes three concepts in the file:
+  * `skillmap`: the root key of the toml file. Typically, it is used to represent a project.
+  * `group`: a group of skills. In each file, it can have multiple groups in it. You can use `group` to represent sub project/component in a project.
+  * `skill`: a specific skill. Each group can have multiple skills in it. You can use `skill` to represent a specific component/module in a sub project/component.
+### skillmap toml table
+* The `skillmap` toml table can have some fields:
+  * `name`: [optional] the name of the skillmap. It will be used as a label in the diagram for the top level node.
+  * `icon`: [optional] a fontawsome icon name. It will be used as an icon in the diagram. You can find the fontawsome icon list [here](https://fontawesome.com/v4.7.0/icons/).
+  * `theme`: [optional] theme for the diagram. Serveral themes are included:
+    * ocean (default theme)
+    * earth
+    * grape
+    * grass
+    * pale
+    * rose
+  * `orientation`: [optional] the orientation of the diagram. [All mermaid's orientations](https://mermaid-js.github.io/mermaid/#/flowchart?id=flowchart-orientation) are supported, including:
+    * TB - top to bottom (default)
+    * TD - top-down/ same as top to bottom
+    * BT - bottom to top
+    * RL - right to left
+    * LR - left to right
+## group/skill toml tables
+* The `group`/`skill` toml table can have some fields:
+  * `name`: [optional] the name of the skillmap/group/skill. It will be used as a label in the diagram. .
+  * `icon`: [optional] a fontawsome icon name. It will be used as an icon in the diagram. You can find the fontawsome icon list [here](https://fontawesome.com/v4.7.0/icons/).
+  * `requires`: [optional] a list of strings. It indicates a list of skill groups or skills to be learned before this learning this skill group/skill. where each string is a toml table name of a group/skill. It will be rendered as an edge(s) from one node to another. 
+
+## Example
+```toml
+[groups.learn_python]
+name = "learn python"
+icon = "rocket"
+    [groups.learn_python.skills.print]
+    name = "print statement"
+    icon = "printer"
+    [groups.learn_python.skills.string]
+    name = "string literal"
+    icon = "book"
+
+[groups.program_with_python]
+name = "program with python"
+icon = "car"
+requires = ["groups.learn_python"]
+```
+In this exmaple, there are:
+* two groups: `groups.learn_python` and `groups.program_with_python`
+* `groups.learn_python` has two skills: 
+  * `groups.learn_python.skills.print` 
+  * `groups.learn_python.skills.string`
+* `groups.program_with_python` requires `groups.learn_python` to be learned first. When drawn in the diagram, it will be rendered as an edge from `groups.learn_python` to `groups.program_with_python`.

justfile

@@ -5,3 +5,9 @@ setup:
 	# install the library into system python
 	rm -fr ./dist
 	poetry build && pip install ./dist/skillmap-*-py3-none-any.whl --force-reinstall
+
+build_sample src="tests/url_shortener.toml" dest="dist/url_shortener.md":
+  echo '```mermaid' > {{ dest }} && skillmap {{ src }} >> {{ dest }} && echo '```' >> {{ dest }}
+
+dev_sample src="tests":
+  find {{ src }} -iname "*.toml" | entr -s "just build_sample"

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "skillmap"
-version = "0.1.0"
+version = "0.2.2"
 description = "Skillmap generates a skill tree from a toml file"
 authors = ["Yue Ni <[email protected]>"]
 

skillmap/main.py

@@ -20,10 +20,10 @@
 def _skillmap_parser():
     parser = argparse.ArgumentParser(prog="skillmap")
     parser.add_argument(
-        "skillmap",
+        "descriptor_toml",
         default=False,
         type=str,
-        help="Skillmap descriptor toml file",
+        help="The path to a toml file describing the skillmap",
     )
     parser.add_argument(
         "--version",
@@ -32,13 +32,13 @@ def _skillmap_parser():
         help="show version number",
     )
 
-    parser.add_argument(
-        "-f",
-        "--format",
-        type=str,
-        default="mermaid",
-        help="export format, [mermaid] are supported",
-    )
+    # parser.add_argument(
+    #     "-f",
+    #     "--format",
+    #     type=str,
+    #     default="mermaid",
+    #     help="export format, [mermaid] are supported",
+    # )
     return parser
 
 
@@ -56,7 +56,7 @@ def generate(skillmap_file, format = None):
 
 def main():
     args = parse_sys_args(sys.argv[1:])
-    skillmap_file = Path(args["skillmap"])
-    format = args["format"]
+    skillmap_file = Path(args["descriptor_toml"])
+    # format = args["format"]
     skillmap_graph = generate(skillmap_file, format)
     print(skillmap_graph)