From 5bae4455387c34eb958f05e290aa5e63e116e5cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D0=BB=D0=B5=D0=BA=D1=81=D0=B0=D0=BD=D0=B4=D1=80?= Date: Mon, 5 Nov 2012 18:56:02 +0200 Subject: [PATCH] docs close to structure, add snippet to autodoc django models --- docs/source/{common.rst => capa.rst} | 0 docs/source/cms.rst | 54 ++++++++ docs/source/common-lib.rst | 9 ++ docs/source/conf.py | 97 ++++++++++++++- docs/source/djangoapps-common.rst | 54 ++++++++ docs/source/djangoapps.rst | 10 ++ docs/source/index.rst | 5 +- docs/source/lms.rst | 141 ++++++++++++++++++++- docs/source/mitx_modules.rst | 14 --- docs/source/overview.rst | 20 +++ docs/source/xmodule.rst | 180 +++++++++++++++++++++++++++ 11 files changed, 564 insertions(+), 20 deletions(-) rename docs/source/{common.rst => capa.rst} (100%) create mode 100644 docs/source/cms.rst create mode 100644 docs/source/common-lib.rst create mode 100644 docs/source/djangoapps-common.rst create mode 100644 docs/source/djangoapps.rst delete mode 100644 docs/source/mitx_modules.rst create mode 100644 docs/source/overview.rst create mode 100644 docs/source/xmodule.rst diff --git a/docs/source/common.rst b/docs/source/capa.rst similarity index 100% rename from docs/source/common.rst rename to docs/source/capa.rst diff --git a/docs/source/cms.rst b/docs/source/cms.rst new file mode 100644 index 0000000000..f83d89f52d --- /dev/null +++ b/docs/source/cms.rst @@ -0,0 +1,54 @@ +******************************************* +Capa module +******************************************* + +.. module:: capa + +Calc +==== + +.. automodule:: capa.calc + :members: + :show-inheritance: + +Capa_problem +============ + +.. automodule:: capa.capa_problem + :members: + :show-inheritance: + +Checker +======= + +.. automodule:: capa.checker + :members: + :show-inheritance: + +Correctmap +========== + +.. automodule:: capa.correctmap + :members: + :show-inheritance: + +Customrender +============ + +.. automodule:: capa.customrender + :members: + :show-inheritance: + +Inputtypes +========== + +.. automodule:: capa.inputtypes + :members: + :show-inheritance: + +Resposetypes +============ + +.. automodule:: capa.responsetypes + :members: + :show-inheritance: diff --git a/docs/source/common-lib.rst b/docs/source/common-lib.rst new file mode 100644 index 0000000000..4fa5eaeb0a --- /dev/null +++ b/docs/source/common-lib.rst @@ -0,0 +1,9 @@ +Common / lib +=============================== +Contents: + +.. toctree:: + :maxdepth: 2 + + xmodule.rst + capa.rst \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 3ef480555d..555dfd4e13 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -18,8 +18,23 @@ import sys, os # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('../..')) # mitx folder -sys.path.insert(0, os.path.join(os.path.abspath('../..'), 'common', 'lib', 'capa')) +sys.path.insert(0, os.path.join(os.path.abspath('../..'), 'common', 'lib', 'capa')) # capa module +sys.path.insert(0, os.path.join(os.path.abspath('../..'), 'common', 'lib', 'xmodule')) # xmodule +sys.path.insert(0, os.path.join(os.path.abspath('../..'), 'lms', 'djangoapps')) # lms djangoapps +sys.path.insert(0, os.path.join(os.path.abspath('../..'), 'cms', 'djangoapps')) # cms djangoapps +sys.path.insert(0, os.path.join(os.path.abspath('../..'), 'common', 'djangoapps')) # common djangoapps + + + +# django specific # import ipdb; ipdb.set_trace() +# Set up the Django settings/environment +# STATIC_URL = '/static/' +# sys.path.insert(0, os.path.join(os.path.abspath('../..'), 'lms', 'envs')) # lms djangoapps +# from django.core.management import setup_environ +# import lms.envs.dev +# import ipdb; ipdb.set_trace() +# setup_environ(lms.envs.dev) # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -246,3 +261,83 @@ texinfo_documents = [ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'http://docs.python.org/': None} + +# from http://djangosnippets.org/snippets/2533/ +# autogenerate models definitions +# THIS_DIR = os.path.dirname(__file__) +# PROJECT_DIR = os.path.join(THIS_DIR, 'relative/path/to/your/project/') +# sys.path.append(PROJECT_DIR) + +import inspect +import lms.envs.dev +from django.core.management import setup_environ +from django.utils.html import strip_tags +from django.utils.encoding import force_unicode + +setup_environ(lms.envs.dev) + + +def process_docstring(app, what, name, obj, options, lines): + # This causes import errors if left outside the function + from django.db import models + from django import forms + from django.forms.models import BaseInlineFormSet + + # Only look at objects that inherit from Django's base MODEL class + if inspect.isclass(obj) and issubclass(obj, models.Model): + # Grab the field list from the meta class + fields = obj._meta._fields() + + for field in fields: + # Decode and strip any html out of the field's help text + help_text = strip_tags(force_unicode(field.help_text)) + + # Decode and capitalize the verbose name, for use if there isn't + # any help text + verbose_name = force_unicode(field.verbose_name).capitalize() + + if help_text: + # Add the model field to the end of the docstring as a param + # using the help text as the description + lines.append(u':param %s: %s' % (field.attname, help_text)) + else: + # Add the model field to the end of the docstring as a param + # using the verbose name as the description + lines.append(u':param %s: %s' % (field.attname, verbose_name)) + + # Add the field's type to the docstring + lines.append(u':type %s: %s' % (field.attname, type(field).__name__)) + # Only look at objects that inherit from Django's base FORM class + # elif (inspect.isclass(obj) and issubclass(obj, forms.ModelForm) or issubclass(obj, forms.ModelForm) or issubclass(obj, BaseInlineFormSet)): + # pass + # # Grab the field list from the meta class + # import ipdb; ipdb.set_trace() + # fields = obj._meta._fields() + # import ipdb; ipdb.set_trace() + # for field in fields: + # import ipdb; ipdb.set_trace() + # # Decode and strip any html out of the field's help text + # help_text = strip_tags(force_unicode(field.help_text)) + + # # Decode and capitalize the verbose name, for use if there isn't + # # any help text + # verbose_name = force_unicode(field.verbose_name).capitalize() + + # if help_text: + # # Add the model field to the end of the docstring as a param + # # using the help text as the description + # lines.append(u':param %s: %s' % (field.attname, help_text)) + # else: + # # Add the model field to the end of the docstring as a param + # # using the verbose name as the description + # lines.append(u':param %s: %s' % (field.attname, verbose_name)) + + # # Add the field's type to the docstring + # lines.append(u':type %s: %s' % (field.attname, type(field).__name__)) + # Return the extended docstring + return lines + + +def setup(app): + # Register the docstring processor with sphinx + app.connect('autodoc-process-docstring', process_docstring) \ No newline at end of file diff --git a/docs/source/djangoapps-common.rst b/docs/source/djangoapps-common.rst new file mode 100644 index 0000000000..f83d89f52d --- /dev/null +++ b/docs/source/djangoapps-common.rst @@ -0,0 +1,54 @@ +******************************************* +Capa module +******************************************* + +.. module:: capa + +Calc +==== + +.. automodule:: capa.calc + :members: + :show-inheritance: + +Capa_problem +============ + +.. automodule:: capa.capa_problem + :members: + :show-inheritance: + +Checker +======= + +.. automodule:: capa.checker + :members: + :show-inheritance: + +Correctmap +========== + +.. automodule:: capa.correctmap + :members: + :show-inheritance: + +Customrender +============ + +.. automodule:: capa.customrender + :members: + :show-inheritance: + +Inputtypes +========== + +.. automodule:: capa.inputtypes + :members: + :show-inheritance: + +Resposetypes +============ + +.. automodule:: capa.responsetypes + :members: + :show-inheritance: diff --git a/docs/source/djangoapps.rst b/docs/source/djangoapps.rst new file mode 100644 index 0000000000..7a8414189a --- /dev/null +++ b/docs/source/djangoapps.rst @@ -0,0 +1,10 @@ +Django applications +=============================== +Contents: + +.. toctree:: + :maxdepth: 2 + + lms.rst + cms.rst + djangoapps-common.rst \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 4c8827189e..92c535a624 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -11,7 +11,10 @@ Contents: .. toctree:: :maxdepth: 2 - mitx_modules.rst + overview.rst + common-lib.rst + djangoapps.rst + Indices and tables ================== diff --git a/docs/source/lms.rst b/docs/source/lms.rst index 0606942b99..ad114a3088 100644 --- a/docs/source/lms.rst +++ b/docs/source/lms.rst @@ -1,12 +1,145 @@ ******************************************* -LMS appication +LMS module ******************************************* .. module:: lms -Models -====== +Branding +======== -.. automodule:: lms.lib +.. automodule:: branding + :members: + :show-inheritance: + +Views +----- + +.. automodule:: branding.views + :members: + :show-inheritance: + +Certificates +============ + +.. automodule:: certificates + :members: + :show-inheritance: + +Models +------ + +.. automodule:: certificates.models + :members: + :show-inheritance: + +Views +----- + +.. automodule:: certificates.views + :members: + :show-inheritance: + +Tests +----- + +.. automodule:: certificates.tests + :members: + :show-inheritance: + +Circuit +======= + +.. automodule:: circuit + :members: + :show-inheritance: + +Course_wiki +=========== + +.. automodule:: course_wiki + :members: + :show-inheritance: + +Courseware +========== + +.. automodule:: courseware + :members: + :show-inheritance: + +Dashboard +========= + +.. automodule:: dashboard + :members: + :show-inheritance: + +Django comment client +===================== + +.. automodule:: django_comment_client + :members: + :show-inheritance: + +Heartbeat +========= + +.. automodule:: heartbeat + :members: + :show-inheritance: + +Instructor +========== + +.. automodule:: instructor + :members: + :show-inheritance: + +Lisenses +======== + +.. automodule:: licenses + :members: + :show-inheritance: + +LMS migration +============= + +.. automodule:: lms_migration + :members: + :show-inheritance: + +Multicourse +=========== + +.. automodule:: multicourse + :members: + :show-inheritance: + +Psychometrics +============= + +.. automodule:: psychometrics + :members: + :show-inheritance: + +Simple wiki +=========== + +.. automodule:: simplewiki + :members: + :show-inheritance: + +Static template view +==================== + +.. automodule:: static_template_view + :members: + :show-inheritance: + +Static book +=========== + +.. automodule:: staticbook :members: :show-inheritance: diff --git a/docs/source/mitx_modules.rst b/docs/source/mitx_modules.rst deleted file mode 100644 index 027fc15a89..0000000000 --- a/docs/source/mitx_modules.rst +++ /dev/null @@ -1,14 +0,0 @@ -MITx Modules -=============================== -Contents: - -.. toctree:: - :maxdepth: 2 - - .. askbot.rst - .. cms.rst - common.rst - .. doc.rst - .. docs.rst - .. fixtures.rst - .. lms.rst \ No newline at end of file diff --git a/docs/source/overview.rst b/docs/source/overview.rst new file mode 100644 index 0000000000..007c7582ad --- /dev/null +++ b/docs/source/overview.rst @@ -0,0 +1,20 @@ +******************************************* +What the pieces are? +******************************************* + +What +==== + +... + +How +=== + +... + + +Who +=== + + +... \ No newline at end of file diff --git a/docs/source/xmodule.rst b/docs/source/xmodule.rst new file mode 100644 index 0000000000..45caa82c30 --- /dev/null +++ b/docs/source/xmodule.rst @@ -0,0 +1,180 @@ +******************************************* +Xmodule +******************************************* + +.. module:: xmodule + +Abtest +====== + +.. automodule:: xmodule.abtest_module + :members: + :show-inheritance: + +Back compatibility +================== + +.. automodule:: xmodule.backcompat_module + :members: + :show-inheritance: + +Capa +==== + +.. automodule:: xmodule.capa_module + :members: + :show-inheritance: + +Course +====== + +.. automodule:: xmodule.course_module + :members: + :show-inheritance: + +Discussion +========== + +.. automodule:: xmodule.discussion_module + :members: + :show-inheritance: + +Editing +======= + +.. automodule:: xmodule.editing_module + :members: + :show-inheritance: + +Error +===== + +.. automodule:: xmodule.error_module + :members: + :show-inheritance: + +Error tracker +============= + +.. automodule:: xmodule.errortracker + :members: + :show-inheritance: + +Exceptions +========== + +.. automodule:: xmodule.exceptions + :members: + :show-inheritance: + +Graders +======= + +.. automodule:: xmodule.graders + :members: + :show-inheritance: + +Hidden +====== + +.. automodule:: xmodule.hidden_module + :members: + :show-inheritance: + +Html checker +============ + +.. automodule:: xmodule.html_checker + :members: + :show-inheritance: + +Html +==== + +.. automodule:: xmodule.html_module + :members: + :show-inheritance: + +Mako +==== + +.. automodule:: xmodule.mako_module + :members: + :show-inheritance: + +Progress +======== + +.. automodule:: xmodule.progress + :members: + :show-inheritance: + +Schematic +========= + +.. automodule:: xmodule.schematic_module + :members: + :show-inheritance: + +Sequence +======== + +.. automodule:: xmodule.seq_module + :members: + :show-inheritance: + +Stringify +========= + +.. automodule:: xmodule.stringify + :members: + :show-inheritance: + +Template +======== + +.. automodule:: xmodule.template_module + :members: + :show-inheritance: + +Templates +========= + +.. automodule:: xmodule.templates + :members: + :show-inheritance: + +Time parse +========== + +.. automodule:: xmodule.timeparse + :members: + :show-inheritance: + +Vertical +======== + +.. automodule:: xmodule.vertical_module + :members: + :show-inheritance: + +Video +===== + +.. automodule:: xmodule.video_module + :members: + :show-inheritance: + +X += + +.. automodule:: xmodule.x_module + :members: + :show-inheritance: + +Xml +=== + +.. automodule:: xmodule.xml_module + :members: + :show-inheritance: