kreyren/Zernit
1
0
Fork 0
Code Issues 129 Pull Requests Releases Activity

Proper documentation #126

New Issue
Open
opened 2020-05-21 19:23:01 +02:00 by Kreyren · 1 comment
Kreyren commented 2020-05-21 19:23:01 +02:00 (Migrated from github.com)
Copy Link
Copy Source

This project depends on a proper documentation for it's implementation of other programming languages and to make a proper abstracting.

Requirements for the documentation

We need a documentation that is easy to understand by a 6yo kid

  1. Basic plain text handling
  2. Graphs
  • Unknown how to develop
  1. Diagrams
  • Unknown
  1. Flow charts
  1. Images
  • Preferably SVG files
  1. Ideally something that updates the documentation based on the file content in our source code

Current options

Each option has a score from -100 to +100 to help with the decision making

Markdown + HTML (github markdown)

-40 Requires pre-rendered graphs and diagrams
+80 Works nicely on GitHub and can be added to each directory to be rendered in GitHub UI

Markdown

-90 Doesn't support HTML by default (?)

Org-mode

-15 Doesn't work nicely on GitHub UI
+50 Allows rendering based on provided logic

  • -? Rendering of logic doesn't work on GitPod
    +60 has a lots of features to make the documentation nice
    -10 has arguably stupid extension file.org

HTML

Seems as bad idea

Javascript-based website

-5 Resource intensive
-40 Might discourage contribution from some contributors

  • +80 The website content can be rendered from a Github Markdown

plain text with pre-rendered images

Seems as pita to make

Custom

TODO: First evaluate previous option

Something else?

Unknown..

Example workflow

Code

#!/bin/sh
# Some copyright

# Shellcheck something..

# FIXME: Not all systems might have uname
KERNEL="$(uname -s | tr :[upper]: :[lower]:)"

case "$KERNEL" in
	Linux) printf '%s\n' "Something!" ;;
	Windows) printf '%s\n' "Nothing!" ;;
	*) efixme "Add sanitization"
esac

Documentation

We need this script to detect used kernel for our program do to things

<Some (ideally interactive)diagram here to make it understandable for the end-user>

[ Show this only if we are relying on uname ]
FIXME: We are using uname which blah blah, but might not be available on all systems

Alternative approach (preferred)

Code

#!/bin/sh
# Some copyright

###! Documentation here
###! blah blah
###! blah blah
###! blah blah
###! blah blah

###! Shellcheck is mandatory for our code blah blah
# Shellcheck something..

###! <output from a program that reads this file and renders the section only if we are relying on uname here>
# FIXME: Not all systems might have uname
KERNEL="$(uname -s | tr :[upper]: :[lower]:)"

case "$KERNEL" in
	###! Linux specific documentation for end-users on Linux
	Linux) printf '%s\n' "Something!" ;;
	###! Windows specific documentation for end-users on Linux
	Windows) printf '%s\n' "Nothing!" ;;
	*) efixme "Add sanitization"
esac

Expecting to return something alike:

Documentation here
blah blah
blah blah
blah blah
blah blah

Shellcheck is mandatory for our code blah blah
\`\`\`sh
# Shellcheck something..
\`\`\`

<output from a program that reads this file and renders the section only if we are relying on uname here>
\`\`\`sh
# FIXME: Not all systems might have uname
KERNEL="$(uname -s | tr :[upper]: :[lower]:)"

<FIXME: Logic conflicts here>
case "$KERNEL" in
	###! Linux specific documentation for end-users on Linux
	Linux) printf '%s\n' "Something!" ;;
	###! Windows specific documentation for end-users on Linux
	Windows) printf '%s\n' "Nothing!" ;;
	*) efixme "Add sanitization"
esac
\`\`\`
<!-- Please keep your request as short as possible, the longer the request the longer it's going to take for us to process it --> This project depends on a proper documentation for it's implementation of other programming languages and to make a proper abstracting. ## Requirements for the documentation We need a documentation that is easy to understand by a 6yo kid 0. Basic plain text handling 1. Graphs - Unknown how to develop 2. Diagrams - Unknown 3. Flow charts - Eclipse's sprotty <https://github.com/eclipse/sprotty> seems as a great option for this 4. Images - Preferably SVG files 5. Ideally something that updates the documentation based on the file content in our source code ## Current options Each option has a score from -100 to +100 to help with the decision making #### Markdown + HTML (github markdown) **-40** Requires pre-rendered graphs and diagrams **+80** Works nicely on GitHub and can be added to each directory to be rendered in GitHub UI #### Markdown **-90** Doesn't support HTML by default (?) #### Org-mode **-15** Doesn't work nicely on GitHub UI **+50** Allows rendering based on provided logic - **-?** Rendering of logic doesn't work on GitPod **+60** has a lots of features to make the documentation nice **-10** has arguably stupid extension `file.org` #### HTML Seems as bad idea #### Javascript-based website **-5** Resource intensive **-40** Might discourage contribution from some contributors - **+80** The website content can be rendered from a Github Markdown #### plain text with pre-rendered images Seems as pita to make #### Custom TODO: First evaluate previous option #### Something else? Unknown.. --- ## Example workflow ### Code ```sh #!/bin/sh # Some copyright # Shellcheck something.. # FIXME: Not all systems might have uname KERNEL="$(uname -s | tr :[upper]: :[lower]:)" case "$KERNEL" in Linux) printf '%s\n' "Something!" ;; Windows) printf '%s\n' "Nothing!" ;; *) efixme "Add sanitization" esac ``` ### Documentation We need this script to detect used kernel for our program do to things <Some (ideally interactive)diagram here to make it understandable for the end-user> [ Show this only if we are relying on `uname` ] FIXME: We are using `uname` which blah blah, but might not be available on all systems --- ## Alternative approach (preferred) ### Code ```sh #!/bin/sh # Some copyright ###! Documentation here ###! blah blah ###! blah blah ###! blah blah ###! blah blah ###! Shellcheck is mandatory for our code blah blah # Shellcheck something.. ###! <output from a program that reads this file and renders the section only if we are relying on uname here> # FIXME: Not all systems might have uname KERNEL="$(uname -s | tr :[upper]: :[lower]:)" case "$KERNEL" in ###! Linux specific documentation for end-users on Linux Linux) printf '%s\n' "Something!" ;; ###! Windows specific documentation for end-users on Linux Windows) printf '%s\n' "Nothing!" ;; *) efixme "Add sanitization" esac ``` Expecting to return something alike: ```markdown Documentation here blah blah blah blah blah blah blah blah Shellcheck is mandatory for our code blah blah \`\`\`sh # Shellcheck something.. \`\`\` <output from a program that reads this file and renders the section only if we are relying on uname here> \`\`\`sh # FIXME: Not all systems might have uname KERNEL="$(uname -s | tr :[upper]: :[lower]:)" <FIXME: Logic conflicts here> case "$KERNEL" in ###! Linux specific documentation for end-users on Linux Linux) printf '%s\n' "Something!" ;; ###! Windows specific documentation for end-users on Linux Windows) printf '%s\n' "Nothing!" ;; *) efixme "Add sanitization" esac \`\`\` ```
Kreyren commented 2020-06-05 08:55:03 +02:00 (Migrated from github.com)
Copy Link
Copy Source

@Uniminin though?

@Uniminin though?
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Assignees
Clear assignees
kreyren (Jacob Hrbek)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: kreyren/Zernit#126
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?