Merge pull request #163 from edx/alex/fix_rake_doc

Alex/fix rake doc

CHANGELOG.rst

@@ -5,6 +5,8 @@ These are notable changes in edx-platform.  This is a rolling list of changes,
 in roughly chronological order, most recent first.  Add your entries at or near
 the top.  Include a label indicating the component affected.
 
+Common: Repairs development documentation generation by sphinx.
+
 LMS: Problem rescoring.  Added options on the Grades tab of the
 Instructor Dashboard to allow all students' submissions for a
 particular problem to be rescored.  Also supports resetting all

common/lib/capa/capa/checker.py

@@ -12,8 +12,8 @@ from path import path
 from cStringIO import StringIO
 from collections import defaultdict
 
-from .calc import UndefinedVariable
-from .capa_problem import LoncapaProblem
+from calc import UndefinedVariable
+from capa.capa_problem import LoncapaProblem
 from mako.lookup import TemplateLookup
 
 logging.basicConfig(format="%(levelname)s %(message)s")

doc/public/course_data_formats/conditional_module/conditional_module.rst

@@ -53,7 +53,7 @@ Examples of conditional depends on poll
     </conditional>
 
 Examples of conditional depends on poll (use <show> tag)
--------------------------------------------
+--------------------------------------------------------
 
 .. code-block:: xml
 

doc/public/course_data_formats/drag_and_drop/drag_and_drop_input.rst

@@ -420,6 +420,6 @@ Draggables can be reused
 .. literalinclude:: drag-n-drop-demo2.xml
 
 Examples of targets on draggables
-------------------------
+---------------------------------
 
 .. literalinclude:: drag-n-drop-demo3.xml

doc/public/course_data_formats/graphical_slider_tool/graphical_slider_tool.rst

@@ -362,7 +362,7 @@ that has to be updated on a parameter's change, then one can define
 a special function to handle this. The "output" of such a function must be
 set to "none", and the JavaScript code inside this function must update the
 MathJax element by itself. Before exiting, MathJax typeset function should
-be called so that the new text will be re-rendered by MathJax. For example,
+be called so that the new text will be re-rendered by MathJax. For example::
 
     <render>
         ...

doc/public/course_data_formats/symbolic_response.rst

@@ -19,11 +19,11 @@ This is a partial list of features, to be revised as we go along:
 
       An example of a problem::
 
-      <symbolicresponse expect="a_b^c + b_x__d" size="30">
-        <textline math="1"
+        <symbolicresponse expect="a_b^c + b_x__d" size="30">
+          <textline math="1"
            preprocessorClassName="SymbolicMathjaxPreprocessor"
            preprocessorSrc="/static/js/capa/symbolic_mathjax_preprocessor.js"/>
-      </symbolicresponse>
+        </symbolicresponse>
 
       It's a bit of a pain to enter that.
 

doc/public/index.rst

@@ -28,6 +28,7 @@ Specific Problem Types
    course_data_formats/conditional_module/conditional_module.rst
    course_data_formats/word_cloud/word_cloud.rst
    course_data_formats/custom_response.rst
+   course_data_formats/symbolic_response.rst
 
 
 Internal Data Formats

docs/source/calc.rst

@@ -0,0 +1,7 @@
+*******************************************
+Calc
+*******************************************
+
+.. automodule:: calc
+    :members:
+    :show-inheritance:

docs/source/capa.rst

@@ -8,14 +8,6 @@ Contents:
 .. toctree::
     :maxdepth: 2
 
-    chem.rst
-
-Calc
-====
-
-.. automodule:: capa.calc
-    :members:
-    :show-inheritance:
 
 Capa_problem
 ============

docs/source/chem.rst

@@ -1,5 +1,5 @@
 *******************************************
-Chem module
+Chemistry modules
 *******************************************
 
 .. module:: chem
@@ -7,7 +7,7 @@ Chem module
 Miller
 ======
 
-.. automodule:: capa.chem.miller
+.. automodule:: chem.miller
     :members:
     :show-inheritance:
 
@@ -47,14 +47,14 @@ Documentation from **crystallography.js**::
 Chemcalc
 ========
 
-.. automodule:: capa.chem.chemcalc
+.. automodule:: chem.chemcalc
     :members:
     :show-inheritance:
 
 Chemtools
 =========
 
-.. automodule:: capa.chem.chemtools
+.. automodule:: chem.chemtools
     :members:
     :show-inheritance:
 
@@ -62,7 +62,7 @@ Chemtools
 Tests
 =====
 
-.. automodule:: capa.chem.tests
+.. automodule:: chem.tests
     :members:
     :show-inheritance:
 

docs/source/cms.rst

@@ -4,86 +4,3 @@ CMS module
 
 .. module:: cms
 
-Auth
-====
-
-.. automodule:: auth
-    :members:
-    :show-inheritance:
-
-Authz
------
-
-.. automodule:: auth.authz
-    :members:
-    :show-inheritance:
-
-Content store
-=============
-
-.. .. automodule:: contentstore
-..     :members:
-..     :show-inheritance:
-
-.. Utils
-.. -----
-
-.. .. automodule:: contentstore.untils
-..     :members:
-..     :show-inheritance:
-
-.. Views
-.. -----
-
-.. .. automodule:: contentstore.views
-..     :members:
-..     :show-inheritance:
-
-.. Management
-.. ----------
-
-.. .. automodule:: contentstore.management
-..     :members:
-..     :show-inheritance:
-
-.. Tests
-.. -----
-
-.. .. automodule:: contentstore.tests
-..     :members:
-..     :show-inheritance:
-
-Github sync
-===========
-
-.. automodule:: github_sync
-    :members:
-    :show-inheritance:
-
-Exceptions
-----------
-
-.. automodule:: github_sync.exceptions
-    :members:
-    :show-inheritance:
-
-Views
------
-
-.. automodule:: github_sync.views
-    :members:
-    :show-inheritance:
-
-Management
-----------
-
-.. automodule:: github_sync.management
-    :members:
-    :show-inheritance:
-
-Tests
------
-
-.. .. automodule:: github_sync.tests
-..     :members:
-..     :show-inheritance:

docs/source/common-lib.rst

@@ -6,4 +6,9 @@ Contents:
    :maxdepth: 2
 
    xmodule.rst
-   capa.rst
+   capa.rst
+   chem.rst
+   sandbox-packages.rst
+   symmath.rst
+   calc.rst
+

docs/source/conf.py

@@ -1,32 +1,30 @@
 # -*- coding: utf-8 -*-
-#
-# MITx documentation build configuration file, created by
-# sphinx-quickstart on Fri Nov  2 15:43:00 2012.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
+#pylint: disable=C0103
+#pylint: disable=W0622
+#pylint: disable=W0212
+#pylint: disable=W0613
+""" EdX documentation build configuration file, created by
+ sphinx-quickstart on Fri Nov  2 15:43:00 2012.
 
-import sys, os
+  This file is execfile()d with the current directory set to its containing dir.
+
+  Note that not all possible configuration values are present in this
+  autogenerated file.
+
+  All configuration values have a default; values that are commented out
+  serve to show the default."""
+
+import sys
+import os
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # 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('.'))
 sys.path.insert(0, os.path.abspath('../..'))  # mitx folder
-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 configuration  - careful here
-import os
-os.environ['DJANGO_SETTINGS_MODULE'] = 'lms.envs.dev'
+os.environ['DJANGO_SETTINGS_MODULE'] = 'lms.envs.test'
 
 
 # -- General configuration -----------------------------------------------------
@@ -36,7 +34,9 @@ os.environ['DJANGO_SETTINGS_MODULE'] = 'lms.envs.dev'
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode']
+extensions = [
+    'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage',
+    'sphinx.ext.pngmath', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -51,17 +51,17 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'MITx'
-copyright = u'2012, MITx team'
+project = u'EdX Dev Data'
+copyright = u'2012-13, EdX team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '1.0'
+version = '0.2'
 # The full version, including alpha/beta/rc tags.
-release = '1.0'
+release = '0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -75,7 +75,7 @@ release = '1.0'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = ['build']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -175,27 +175,27 @@ html_static_path = ['_static']
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'MITxdoc'
+htmlhelp_basename = 'edXDocs'
 
 
 # -- Options for LaTeX output --------------------------------------------------
 
 latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+    # The paper size ('letterpaper' or 'a4paper').
+    #'papersize': 'letterpaper',
 
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
+    # The font size ('10pt', '11pt' or '12pt').
+    #'pointsize': '10pt',
 
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
+    # Additional stuff for the LaTeX preamble.
+    #'preamble': '',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'MITx.tex', u'MITx Documentation',
-   u'MITx team', 'manual'),
+    ('index', 'edXDocs.tex', u'EdX Dev Data Documentation',
+     u'EdX Team', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -224,8 +224,8 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'mitx', u'MITx Documentation',
-     [u'MITx team'], 1)
+    ('index', 'edxdocs', u'EdX Dev Data Documentation',
+     [u'EdX Team'], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -238,9 +238,9 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'MITx', u'MITx Documentation',
-   u'MITx team', 'MITx', 'One line description of project.',
-   'Miscellaneous'),
+    ('index', 'EdXDocs', u'EdX Dev Data Documentation',
+     u'EdX Team', 'EdXDocs', 'One line description of project.',
+     'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -265,8 +265,12 @@ from django.utils.encoding import force_unicode
 
 
 def process_docstring(app, what, name, obj, options, lines):
+    """Autodoc django models"""
+
     # This causes import errors if left outside the function
     from django.db import models
+
+    # If you want extract docs from django forms:
     # from django import forms
     # from django.forms.models import BaseInlineFormSet
 
@@ -326,5 +330,6 @@ def process_docstring(app, what, name, obj, options, lines):
 
 
 def setup(app):
-    # Register the docstring processor with sphinx
+    """Setup docsting processors"""
+    #Register the docstring processor with sphinx
     app.connect('autodoc-process-docstring', process_docstring)

docs/source/index.rst

@@ -1,10 +1,10 @@
-.. MITx documentation master file, created by
+.. EdX Dev documentation master file, created by
    sphinx-quickstart on Fri Nov  2 15:43:00 2012.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to MITx's documentation!
-================================
+Welcome to EdX's Dev documentation!
+===================================
 
 Contents:
 

docs/source/overview.rst

@@ -1,20 +1,9 @@
 *******************************************
-What the pieces are?
+Overview
 *******************************************
 
-What
-====
 
-...
+This is EdX Dev documentation, mainly extracted from docstrings.
+Autogenerated by Sphinx from python code.
+Soon support for JS will be impemented.
 
-How
-===
-
-...
-
-
-Who
-===
-
-
-...

docs/source/sandbox-packages.rst

@@ -0,0 +1,11 @@
+*******************************************
+Sandbox-packages
+*******************************************
+.. module:: sandbox-packages
+
+Loncapa
+=======
+
+.. automodule:: loncapa.loncapa_check
+    :members:
+    :show-inheritance:

docs/source/symmath.rst

@@ -0,0 +1,31 @@
+*******************************************
+Symmath
+*******************************************
+
+.. module:: symmath
+
+
+Formula
+=======
+
+.. automodule:: symmath.formula
+    :members:
+    :show-inheritance:
+
+Symmath check
+=============
+
+.. automodule:: symmath.symmath_check
+    :members:
+    :show-inheritance:
+
+Symmath tests
+=============
+
+.. automodule:: symmath.test_formula
+    :members:
+    :show-inheritance:
+
+.. automodule:: symmath.test_symmath_check
+    :members:
+    :show-inheritance:

docs/source/xmodule.rst

@@ -144,13 +144,6 @@ Templates
     :members:
     :show-inheritance:
 
-Time parse
-==========
-
-.. automodule:: xmodule.timeparse
-    :members:
-    :show-inheritance:
-
 Vertical
 ========
 

rakefiles/docs.rake

@@ -22,9 +22,7 @@ task :showdocs, [:options] do |t, args|
         path = "docs"
     end
 
-    Dir.chdir("#{path}/build/html") do
-        Launchy.open('index.html')
-    end
+    Launchy.open("#{path}/build/html/index.html")
 end
 
 desc "Build docs and show them in browser"

rakefiles/tests.rake

@@ -33,6 +33,17 @@ def run_acceptance_tests(system, report_dir, harvest_args)
     test_sh(django_admin(system, 'acceptance', 'harvest', '--debug-mode', '--tag -skip', harvest_args))
 end
 
+# Run documentation tests
+desc "Run documentation tests"
+task :test_docs do
+    # Be sure that sphinx can build docs w/o exceptions.
+    test_message = "If test fails, you shoud run %s and look at whole output and fix exceptions.
+(You shouldn't fix rst warnings and errors for this to pass, just get rid of exceptions.)"
+    puts (test_message  % ["rake doc"]).colorize( :light_green )
+    test_sh('rake builddocs')
+    puts  (test_message  % ["rake doc[pub]"]).colorize( :light_green )
+    test_sh('rake builddocs[pub]')
+end
 
 directory REPORT_DIR
 
@@ -103,7 +114,7 @@ TEST_TASK_DIRS.each do |dir|
 end
 
 desc "Run all tests"
-task :test
+task :test => :test_docs
 
 desc "Build the html, xml, and diff coverage reports"
 task :coverage => :report_dirs do