google / google/python-fire

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

Abierto
#237 5 comentarios 1 reacción 0 asignados Ver en GitHub
documentation
Lenguaje dominante
Python
Estrellas
28.2k
Forks
1.5k
Métricas de merge de PR
Sin PR fusionados en 30 d

Descripción

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

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.