Argument names and short versions

[tommyod]

Current output

The current treedoc --help output is:

usage: treedoc [-h] [--level [LEVEL]] [--subpackages] [--modules] [--private]
               [--magic] [--tests] [--printer [{simple,dense}]]
               [--signature {0,1,2}] [--docstring {0,1,2,3,4}]
               [--info {0,1,2,3,4}]
               [obj]

Minimalistic documentation in a tree structure.

positional arguments:
  obj                   The object

optional arguments:
  -h, --help            show this help message and exit

traversal:
  The arguments are common to every printer.

  --level [LEVEL]       descend only level directories deep.
  --subpackages         descend into subpackages, i.e. numpy -> numpy.linalg
  --modules             descend into every module in a package.
  --private             show private objects, i.e. _func(x).
  --magic               show magic methods, i.e. __add(self, other)__.
  --tests               show tests, i.e. test_func().

printing:
  The meaning of the arguments varies depending on the printer.

  --printer [{simple,dense}]
                        printer to use, defaults to 'simple'
  --signature {0,1,2}   how much signature information to show.
  --docstring {0,1,2,3,4}
                        how much docstring information to show.
  --info {0,1,2,3,4}    how much general information to show.

Report issues and contribute on https://github.com/tommyod/treedoc.

Discussion points

I would like to:

1. Land a good, descriptive tagline for the project. The current one is "Minimalistic documentation in a tree structure."
2. Have good names for the arguments in general. They must be standard names as well as descriptive.
3. Ideally have arguments with unique first characters, so that we can have -m as an alias for --modules. Currently some argument names clash, i.e. --signature and --subpackages. We can
   1. rename them
   2. use capital letters for one of them, i.e. -s short for --signature and -S short for --subpackages
   3. shorten them to e.g. -sig short for --signature and -sub short for --subpackages

Thoughts

• obj: can be called "obj" or "object".
• level: the linux command tree calls this "level", and uses -L. The linux command find has the argument -maxdepth, and uses the wording Descend at most levels... in the man page. In the literature on trees the word "depth" is more commonly used.
• subpackages: could also be called "packages", but "subpackages" is more descriptive.
• modules: a module is just a python file, so it could be called "files". but "module" is the proper word in my opinion.
• private: not many options here.
• magic: these methods are commonly called "dunder methods" or "magic methods". in the official docs they called called "special attributes".
• tests: simple filter for objects whose names start with "test". Seems like a reasonable name.
• printer: the type of printer to use. could be called "output" or something similar too. The classes are called "printers" in the source code. They could've been called "printers", "formatters", "outputters", etc.
• signature: in the inspect built in module, the terms "arg spec" and "signature" are both used. Signature is clearer in my opinion.
• docstring: Not much to say about this. Could've been called "docs" og "documentation", but the "docstring" is specifically the string under the definition, while "documentation" is more general.
• info: general level of information. This can be called "detail", "information", "verbosity", etc too.

---

I'm opening this Issue to think about this. If we can settle the terminology early on we won't have too many iterations with rewording. Do you have any thoughts @smu095 ?

[smu095]

I think you have done a really good job already. Initial thoughts:

I agree that finding a synonym for subpackages would be preferable, but I can't really see any alternatives that are better. folders could be an option, but it is less than ideal because it abstracts away what we are actually interested in. children is an alternative, but suffers from the same problem as folders. Furthermore, it is a bit ambiguous. I think using capital letters as abbreviations is probably the best alternative.

I find depth a bit more expressive than level, as level implies an ascent instead of a descent.