Flask-Autodoc: génération automatique de doc ============================================ ![category](développement) ![tag](python) ![tag](flask) Quand on utilise un framework web comme flask pour faire un serveur de service par exemple il est parois utile de pouvoir générer une documentation facile d'accès (mode web) pour les utilisateurs. Pour cela flask possède une extension Flask-Autodoc Installation ------------ ```bash pip install flask-autodoc ``` Utilisation ----------- Pour une utilisation complète je vous laisse voir le documentation officielle de l'extension sur https://github.com/acoomans/flask-autodoc ```python from flask import Flask from flask.ext.autodoc import Autodoc app = Flask(__name__) auto = Autodoc(app) @app.route('/user/') @auto.doc() def show_user(id): "mon aide en ligne" return user_from_database(id) @app.route('/documentation') def documentation(): return auto.html() if __name__ == "__main__": app.run() ``` et voilà le résultat ![flaskdoc.png](./upload/flaskdoc.png) ```note il est possible de modifier le template ``` ```note il est possible de gérer une notion de groupe de documentation ``` Utilisation avancée ------------------- Il est possible de changer la sortie html de l'autodoc et d'ajouter des fonctions. Il est par exemple possible de faire traiter les docstrings des fonctions par le module docutils. ```python from flask import Flask from flask.ext.autodoc import Autodoc try: from docutils import core RESTIFY=True except: RESTIFY = False app = Flask(__name__) auto = Autodoc(app) def rsttohtml(rst): if RESTIFY: return core.publish_parts(rst, writer_name='html')['html_body'] return '
%s
' % rst @app.route('/user/') @auto.doc() def show_user(id): """ mon **aide** en ligne sur plusieurs lignes """ return user_from_database(id) @app.route('/documentation') def documentation(): return auto.html(template='myautodoc.html', rsttohtml=rsttohtml) if __name__ == "__main__": app.run() ``` et il faut ajouter le fichier **myautodoc.html** dans un dossier template au niveau du fichier python ```html {% if title is defined -%} {{title}} {% else -%} Documentation {% endif -%}

{% if title is defined -%} {{title}} {% else -%} Documentation {% endif -%}

{% for doc in autodoc %}

{{doc.rule|escape}}

    {% for method in doc.methods -%}
  • {{method}}
  • {% endfor %}
    {% for arg in doc.args %}
  • {{arg}} {{doc.defaults[arg]}}
  • {% endfor %}

{{ rsttohtml(doc.docstring)|safe }}

{% endfor %} ```