API metrics auto-documentation with sphinx.

django/Dockerfile

@@ -11,6 +11,9 @@ RUN apt-getq update && apt-getq install	\
   python3-crypto python3-natsort python3-aiohttp python3-aioredis supervisor	\
   python3-ipy python3-django-taggit python3-iso8601 python3-robot-detection	\
   python3-sqlparse \
+  # documentation
+  python3-sphinx \
+  make \
   # generate the DB schema with graph_models, cf docs/generate_models_png.sh
   python3-django-extensions python3-pydotplus
 

django/allgo/api/v1/__init__.py

+"""
+.. automodule:: api.v1.metrics
+   :members:
+.. automodule:: api.v1.mixins
+   :members:
+.. automodule:: api.v1.views
+   :members:
+"""

django/docs/conf.py

@@ -19,10 +19,12 @@
 #
 import os
 import sys
-from django.conf import settings
+import django
 
 sys.path.insert(0, os.path.abspath('..'))
-settings.configure()
+sys.path.insert(0, os.path.abspath('../allgo'))
+os.environ['DJANGO_SETTINGS_MODULE'] = 'config.settings'
+django.setup()
 
 
 # -- General configuration ------------------------------------------------
@@ -172,6 +174,3 @@ texinfo_documents = [
      author, 'Allgo', 'One line description of project.',
      'Miscellaneous'),
 ]
-
-
-

django/docs/dev/api.rst

+.. _dev-doc:
+
+metrics.py
+==========
+
+.. automodule:: api.v1.metrics
+   :members:
+
+Accessories
+===========
+
+The metrics function are accessed through django Metrics view.
+
+.. autoclass:: api.v1.views.Metrics
+   :members:

django/docs/dev/mixins.rst

+.. _dev-mixins:
+
+In Django, mixins are used to provide shared functionnality to view (almost like interface).
+
+Django mixins used
+-------------------
+(from django.contrib.auth.mixins), more infos on `mixin <https://docs.djangoproject.com/en/2.1/topics/auth/default/>`_
+      
+  LoginRequiredMixin
+    prepend your code with
+     ``if not request.user.is_authenticated: redirect/render``
+
+    It is used for website views accessible only for logged in users.
+
+  UserPassesTestMixin
+    prepend your code with
+     ``if not your_test_func: redirect/render``
+
+    It is used for website views accessible only for logged in users that pass the test.
+
+    The test usually checks some permissions.
+
+
+AllGo main mixins
+------------------
+
+.. automodule:: main.mixins
+   :members:
+
+
+AllGo Api mixin
+----------------
+
+.. automodule:: api.v1.mixins
+   :members:

django/docs/index.rst

@@ -13,6 +13,21 @@ applications. This documentation is related to its front-end. Please see the
    readme
    installation
 
+Developer docs
+--------------
+
+  api
+
+  ..  toctree::
+
+      dev/api
+
+  mixin
+
+  ..  toctree::
+
+      mixins <dev/mixins>
+
 Additional Notes
 ----------------