google / google/python-fire

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

Aperta
#237 5 commenti 1 reazione 0 assegnatari Vedi su GitHub
documentation
Lingua principale
Python
Stelle
28.2k
Fork
1.5k
Metriche di merge delle PR
Nessuna PR unita negli ultimi 30g

Descrizione

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](https://google.github.io/python-fire/guide/) and/or [here](https://github.com/google/python-fire) 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](https://github.com/google/python-fire/issues/114) and perhaps also in the troubleshooting section [here](https://google.github.io/python-fire/troubleshooting/)?

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.