Documentation de construction
Si vous avez apporté des modifications importantes à la documentation, vous pouvez créer une version locale pour visualiser le rendu de vos modifications. Vous devrez installer Sphinx, l'extension Napoleon (pour activer la prise en charge des docstrings NumPy) et le thème «Read the Docs». Pour ce faire, installez les prérequis docs optionnels.
Pour Blocks :
| $ pip install --upgrade git+git://github.com/user/blocks.git#egg=blocks[docs] |
Pour Fuel :
| $ pip install --upgrade git+git://github.com/user/fuel.git#egg=fuel[docs] |
Une fois les exigences installées, vous pouvez créer une copie de la documentation en exécutant la commande suivante à partir du répertoire des blocs racine (ou du carburant).
| $ sphinx-build -b html docs docs/_build/html |
Docstrings
Blocks et Fuel respectent les normes de docstrings NumPy. Pour une introduction rapide, consultez les exemples de docstrings conformes de NumPy ou Napoleon. Quelques erreurs courantes à éviter :
- Il n'y a pas de saut de ligne après les guillemets ouvrants (""").
- Il y a une ligne vide avant les guillemets fermants (""").
- Le résumé ne doit pas dépasser une ligne.
Les docstrings sont formatées avec reStructuredText et bénéficient de toutes les fonctionnalités de formatage offertes. Elles sont converties en documentation HTML grâce au service Read the Docs. Une fois le code fusionné, assurez-vous que la documentation a été correctement compilée et que vos docstrings sont correctement restituées en consultant la documentation en ligne (pour Blocks ou Fuel, étant automatiquement mise à jour).
La rédaction de doctests est encouragée et ils sont exécutés dans le cadre de la suite de tests. Ils doivent utiliser la syntaxe Python 3.
Références et Intersphinx
Sphinx permet de référencer d'autres objets du cadre d'application. Cela crée automatiquement des liens vers la documentation API de cet objet (si elle existe).
|
This is a link to :class:`SomeClass` in the same file. If you want to reference an object in another file, you can use a leading dot to tell Sphinx to look in all files e.g. :meth:`.SomeClass.a_method`. |
Intersphinx est une extension vous permettant de référencer la documentation d'autres projets tels que Theano, NumPy et Scipy.
|
The input to a method can be of the type :class:`~numpy.ndarray`. Note that in this case we need to give the full path. The tilde (~) tells Sphinx not to render the full path (numpy.ndarray), but only the object itself (ndarray). |
Avertissement
En raison d'un bogue dans Napoleon, vous ne pouvez pas utiliser la référence à un type dans la section «Returns» de votre docstring sans lui attribuer un nom. Le rendu est incorrect :
|
Returns ------- :class:`Brick` The returned Brick. |
Mais cela le fait :
|
Returns ------- retured_brick : :class:`Brick` The returned Brick. |