Y a-t-il des alternatives réelles à restructurétext pour Python documentation?
Je commence une source ouverte Python projet bientôt et j'essaie de décider à l'avance comment écrire mes doctorats. La réponse évidente utiliserait restructurétext et Sphinx avec Autodoc, car je suis == Réally Comme l'idée de documenter simplement mon code dans mes docstrings, Sphinx construit automatiquement une API DOC pour moi.
Le problème est la syntaxe restructuréeTextText qu'il utilise - je pense que c'est complètement illisible avant sa rendu. Par exemple:
[. : Type Field_storage: Filetstorage [.____]: paramètre temporaire: s'il faut ou non supprimer le fichier lorsque l'instance de fichier [.____] est la destruction [.____]: type temporaire: BOOL [.____]
Vous devez vraiment Ralentissez et prenez une minute pour donner un sens à partir de ce fouillis syntaxique. J'aime bien plus la voie de Google ( Google Python ), quelle contrepartie à ce qui précède ressemble à ceci:
Argument: Chemin (STR): Le chemin du fichier à envelopper Champ_storage (filestorage): L'instance de filestage à envelopper [.____] ou ne pas supprimer le fichier lorsque le fichier est détruit
Way mieux! Mais bien sûr, Sphinx n'aura aucune de cela et rend tout le texte après "arguments:" dans une longue ligne.
Donc, pour résumer - avant d'aller et de défiler ma base de code avec cette syntaxe restructuréeTextText, j'aimerais savoir s'il existe de véritables alternatives à l'utiliser et à Sphinx, écrivant simplement mon propre API Doc. Par exemple, y a-t-il une extension pour Sphinx qui gère le style de docstring de Guide de Style Google?
J'ai créé une extension SPHINX qui analyse à la fois Google Style et Numpy Soctstrings, et les convertit à la standard restructurétext.
Pour l'utiliser, installez-le simplement:
$ pip install sphinxcontrib-napoleon
Et activez-le dans Conf.py:
# conf.py
# Add autodoc and napoleon to the extensions list
extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon']
Plus de documentation sur Napoléon ici .
Je ne pense pas qu'il y ait quelque chose de mieux que sphinx pour documenter python projets pour le moment.
Pour avoir une doctrine plus claire, mon choix préféré utilise sphinx ensemble avec numpydoc . Basé sur votre exemple, cela ressemblerait à:
def foo(path, field_storage, temporary):
"""This is function foo
Parameters
----------
path : str
The path of the file to wrap
field_storage : :class:`FileStorage`
The :class:`FileStorage` instance to wrap
temporary : bool
Whether or not to delete the file when the File instance
is destructed
Returns
-------
describe : type
Explanation
...
Examples
--------
These are written in doctest format, and should illustrate how to
use the function.
>>> a=[1,2,3]
>>> print [x + 3 for x in a]
[4, 5, 6]
...
"""
pass
(Un exemple complet est ici ), la sortie HTML ressemblera Ceci
Je pense que la structure du fichier RST est plus claire et plus lisible. Le guide donne une plus grande information et des conventions. L'extension numpydoc fonctionne avec autodoc aussi.
J'utilise épydoc et pas Sphinx, cette réponse peut donc ne pas s'appliquer.
La syntaxe restructuréeText que vous décrivez pour la documentation des méthodes et des fonctions n'est pas la seule possible. De loin, je préfère décrire les paramètres à l'aide d'une liste de définitions consolidée , qui est très similaire à celle de Google Way:
:Parameters:
path : str
The path of the file to wrap
field_storage: FileStorage
The FileStorage instance to wrap
temporary: bool
Whether or not to delete the file when the File instance is destructed
J'essaierais si Sphix le soutient. Si ce n'est pas que vous ne pouvez pas envisager d'utiliser Epydoc juste pour cela (bien que ce ne soit pas utilisé activement en ce moment).
En réalité, restructurétext ainsi que le guide de style de pep8 Appliquer principalement pour coder la bibliothèque standard de Python elle-même, bien que beaucoup de programmeurs tiers se conforment également à cela.
Je suis d'accord avec vous que le style des arguments de Google est beaucoup mieux à partir d'une perspective dans le code. Mais vous devriez être capable de générer une telle doctorat avec Sphinx aussi, avec les nouvelles lignes et indentation préservées . Cela ne rend pas aussi beau que avec un formatage plus sphinxy cependant.
Quoi qu'il en soit, vous n'avez pas devez utiliser Sphinx, et à la manière, le module autodoc de Sphinx est définitivement une petite partie de celui-ci. Vous pouvez pratiquement utiliser n'importe quel générateur de documentation capable de récupérer le contenu de Doctstrings, comme - épydoc (quel soutien épytext ainsi que restructurétext, javadoc ou texte ) ou pydoctor , voire plus universel comme Doxygen .
Mais définitivement, Sphinx est assez Pythonic , très pratique à utiliser avec Python et rendre votre code compatible avec l'écosystème de Python. Je pense que vous êtes pas le seul qui pense que c'est un "manque". Peut-être qu'ils prendront en compte ces plaintes à l'avenir, ou peut-être que vous pourriez même envisager de modyfier le module autodoc par vous-même, ne devrait pas être très difficile, c'est en python, ce serait un bon exercice.
Vous CAN Écrivez doctrings dans n'importe quel format que vous aimez. Cependant, pour le bien de chaque autre Python programmeur, il est préférable d'utiliser le balisage et les outils qu'ils connaissent déjà. Leur vie est plus facile si vous vous tenez au repos et à Sphinx.
Python rend le contenu des docstrations disponibles en tant que __doc__ Attribut attaché à l'objet Fonction/Classe/Variable.
Donc, vous pouvez écrire trivialement d'écrire un fichier Python) qui convertit la documentation de tout format que vous aimez dans le format que vous aimez. Vous pouvez même utiliser le style Javadoc, ou XML, ou autre.
Incidemment, étant donné que Sphinx est écrit en Python, il est nécessaire de prendre une entrée non-RST est juste une question d'écriture d'une petite quantité de Python code.
vous devez juste commencer une nouvelle ligne et ajouter un robinet après chaque nom de variable. Ensuite, il est rendu dans plusieurs lignes avec des noms de variables audacieuses consécutives:
Args:
path (str):
The path of the file to wrap
field_storage (FileStorage):
The FileStorage instance to wrap
temporary (bool):
Whether or not to delete the file when the File
instance is destructed