Add docs page with documentation on docstring style(s) supported/expected

[aaronsteers]

Note: Given a little bit of guidance on what formats are supported, I'm available to contribute to the below and/or create a PR.

User Story:

As a developer using Fire, I would like to have a page or section in the Fire documentation here and/or here which gives guidance on which docstyle formats are supported (docBlockr, Google, Numpy, Sphinx, PEP0257) - including either link to the respective syntax guidelines or else sample code for each supported style. And specifically, I am referring to the expected format of function args (type and description) and return values (type and/or description).

Additional Info:

I love love love using Fire to automatically create CLIs for my python libraries! That said, I'm increasingly trying to make sure these CLIs are self-documenting and that --help outputs properly describe the inputs expected. I've spent a lot of energy trying to understand (1) what docstyle formats are out in the world and being actively used/promoted, and (2) which if any of those are supported by the Fire project in a way that the correct descriptions and types would be mapped into the help text of each cli argument. From trial and error and spelunking the closed issues in this repo, I believe I can say confidently that the numpy format is supported. But beyond that, I'm not sure.

Two inquiries:

1. Any guidance on what style(s) are promoted or being supported currently?
2. Would a PR be accepted if I were to add at least some additional info where docstrings are mentioned here and perhaps also in the troubleshooting section here?

[dbieber]

Hello, great idea.

We currently support Google, Numpy, and rst (Sphinx) style docstrings. The docstring support is best-effort, and notably many features of rst docstrings are not currently handled. Additional limitations are listed at the top of https://github.com/google/python-fire/blob/v0.3.0/fire/docstrings.py.

Yes, a PR adding this to the documentation sounds good. I think we should begin by adding a section to the end of docs/using-cli.md about "Documenting your CLI".

[dbieber]

We chose to support those three because they seem to be the three most common docstring formats. Note we made this choice by googling and anecdotal evidence though, we don't have the numbers to back it up.

[aaronsteers]

@dbieber - Incredibly helpful info, thank you! I'll try to take a stab at this over the next few days and I'll use the location you mention above. 👍