What is the difference between a man page and --help for a Python script?

Question

I'm currently developing some Standard Operation Procedures for the company I work for. I'm starting with the very small examples; like scripts. There are currently several scripts being written in different languages. The idea is to stick with the best practices of each language for when developing a tool. The real problem for the business is that how to use a script and what the script is used for is passed by word of mouth.

Therefore for each repository, I'll provide a SOP for:

1. User Manual

2. Coding practices.

3. Version Control best practices.

4. Help documentation

Starting with #4 I know that in Python a Script can be developed with help docstring embedded into the code. I was wondering then; what is the difference between this approach and the actual man pages?

Most of the developers here are working on Windows.

In terms of best practices both approaches should be required or just the embedded Python --help documentation?

Answer 1

I guess the recommended way for Python scripts to be documented is using the ArgumentParser (please see the last example on https://docs.python.org/2/howto/argparse.html#conflicting-options):

$ python prog.py --help
usage: prog.py [-h] [-v | -q] x y

calculate X to the power of Y

positional arguments:
  x              the base
  y              the exponent

optional arguments:
  -h, --help     show this help message and exit
  -v, --verbose
  -q, --quiet

what is the difference between this approach and the actual man pages?

Most of the developers here are working on Windows.

The man pages are a standard for Unix-like systems. Therefore, for this specific Python script case, I find it better to use the standards recommended by the Python community for documentation.