Improve technical instruction and add -version flag

[XingerTang]

Related Issue

Closes #230
Closes #204

What changed

• Update technical instruction, see Improve technical code instruction of the contribution guide #230
• Add -version flag for Report version via -version #204
• Add some links for a quicker start for new users

Why this change

• Clearer instructions for developers
• Improve usability for users

Submodule changes

No change made for this PR, but update the reference to the existing most recent commit on the devel branch of https://github.com/AlphaGenes/tinyhouse (34da21f)

Notes / Risks

• All the tests passed

[XingerTang]

A preview of the new version: https://xingertang-alphapeel.readthedocs.io/en/doc-issue-230-technical-instruction/index.html

[gregorgorjanc]

@XingerTang I have reviewed your changes. This looks very comprehensive - good job! I think this is ready to merge, so go ahead doing that if you don't plan any additional commits to this PR.

[XingerTang]

@gregorgorjanc I made a typo in the last commit I just pushed, that I typed --version instead of -version, which latter is used in the code, also in the original issue. But at the same time, I noticed that the general convention for the multicharacter option is to use the double hyphen (see discussion in https://serverfault.com/a/387936).

There are also more discussions here (https://softwareengineering.stackexchange.com/questions/70357/command-line-options-style-posix-or-what). Suggesting using a single hyphen throughout for everything, or the double hyphen for long options.

We are currently using -h, --help, and all single hyphens for the remaining.

I think maybe we can choose one of the standards and stick with it.

[XingerTang]

I just made the change, fixing the typo back to -version, but keep the discussion open.

[gregorgorjanc]

Yeah, I thought about single and double hyphen flags/options too! Since many of our flags are quite complex/long, it will be hard to get short versions and these are tricky to remember unless users use a tool all the time (like some shell tools), so we will largely have only long versions and then using single - is fine, I guess; except -h and --help, which is ok as that gives users two entries to help. We could change --help to -help and just use single - for everything and be done with it. Happy to follow your choice;)

[XingerTang]

Yeah, I thought about single and double hyphen flags/options too! Since many of our flags are quite complex/long, it will be hard to get short versions and these are tricky to remember unless users use a tool all the time (like some shell tools), so we will largely have only long versions and then using single - is fine, I guess; except -h and --help, which is ok as that gives users two entries to help. We could change --help to -help and just use single - for everything and be done with it. Happy to follow your choice;)

I just checked the tinyhouse code, while the help message printed out suggests that we need to use -h or --help for the help message, the code actually also supports -help flag.

The difference arises from the built-in help message for the option -h and --help, which is directly generated by the print_help provided by the argparse module, and not written by us.

I think it is possible to modify it by disabling the automatic help options support, as shown in https://docs.python.org/3/library/argparse.html#add-help

I suggest we can keep the support for the --help as it is a general standard, but also emphasises that we can do -help.

It would require modifications in tinyhouse, therefore I suggest we merge this one first, and I will open a new issue in tinyhouse to make the change.

[gregorgorjanc]

I would not disable, if we can get -h and -help from our side and also --help from arg parse then even better. Given this state let's advertise in the docs that we can use -h and -help so we focus on single dash options only.

[XingerTang]

I would not disable, if we can get -h and -help from our side and also --help from arg parse then even better. Given this state let's advertise in the docs that we can use -h and -help so we focus on single dash options only.

I just added -help to the docs.

For the built-in help options, we might need to disable them to generate a sensible help message. As the automatic generation would always show a line of

options:
  -h, --help            show this help message and exit

At the top, regardless of whether we add -help.

We can add a new option argument with all three options written together.

[gregorgorjanc]

Huh, there is always something else to do ... Is We can add a new option argument with all three options written together. a minor bit? If yes, go ahead and do it. If not, let's wrap up. I checked the changes and all looks well. Do you plan any more changes?

[XingerTang]

Huh, there is always something else to do ... Is We can add a new option argument with all three options written together. a minor bit? If yes, go ahead and do it. If not, let's wrap up. I checked the changes and all looks well. Do you plan any more changes?

It's quite easy to implement, a simple example is below. But the code should be in tinyhouse, I will open the issue.

>>> import argparse
>>> parser = argparse.ArgumentParser(add_help=False)
>>> parser.add_argument('-h', '-help', '--help', help='display help message')
_StoreAction(option_strings=['-h', '-help', '--help'], dest='help', nargs=None, const=None, default=None, type=None, choices=None, required=False, help='display help message', metavar=None, deprecated=False)
>>> parser.print_help()
usage: [-h HELP]

options:
  -h, -help, --help HELP
                        display help message
>>> exit()

No other changes are planned here. I can soon squash the commits and merge this.

[gregorgorjanc]

Aha, having that in tinyhouse is even better! Time to squash and merge this PR too @XingerTang ;)