google / google/python-fire

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

Ouverte
#237 5 commentaires 1 réaction 0 personnes assignées Voir sur GitHub
documentation
Langage dominant
Python
Étoiles
28.2k
Forks
1.5k
Métriques de merge des PR
Aucune PR mergée en 30 j

Description

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/)?

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.