diff --git a/docs/README.rst b/docs/README.rst index 120469da10..91439343fc 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -6,6 +6,7 @@ The following documentation projects have been moved to the `edx-documentation`_ * course_authors * data +* developers * install_operations * mobile * OLX diff --git a/docs/en_us/developers/Makefile b/docs/en_us/developers/Makefile deleted file mode 100644 index 58e5370a97..0000000000 --- a/docs/en_us/developers/Makefile +++ /dev/null @@ -1,164 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -PAPER ?= -BUILDDIR ?= build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -Q_FLAG = - -ifeq ($(quiet), true) -Q_FLAG = -Q -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = $(Q_FLAG) -d $(BUILDDIR)/doctrees -c source $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/edX.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/edX.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/edX" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/edX" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/en_us/developers/README.rst b/docs/en_us/developers/README.rst new file mode 100644 index 0000000000..a67c3930a7 --- /dev/null +++ b/docs/en_us/developers/README.rst @@ -0,0 +1,46 @@ +###################### +EdX Developer's Guide +###################### + +We have moved the edX Developer's Guide to the `edx-documentation`_ repository +as of January 13, 2015. + +By moving documentation to its own repository, we will be better able to +develop workflows, manage versioning, create translations, and automate +testing, without complicating ongoing development of the edX Platform. + +.. _edx_documentation: https://github.com/edx/edx-documentation + +****************************** +EdX Platform Docstrings +****************************** + +We are in the process of creating a new project to publish docstrings for the +edX Platform. Docstrings will be included for CMS, LMS, and Common modules. + +This project will remain in the edX Platform repository, in the docs/en-us +directory. + +****************************** +View Published Documentation +****************************** + +EdX documentation is published through Read the Docs. Links to all published +documentation are available through `docs.edx.org`_. + +.. _docs.edx.org: http://docs.edx.org + +****************************** +Submit Documentation Issues +****************************** + +We welcome input from the community on any documentation issues. You can +submit issues to the Documentation project in the `Open edX JIRA board`_. + +You will need to `create a free JIRA account`_ account before you can submit your first +ticket. + +.. _create a free JIRA account: https://openedx.atlassian.net/admin/users/sign-up +.. _Open edX JIRA board: https://openedx.atlassian.net + +You can also email docs@edx.org. diff --git a/docs/en_us/developers/__init__.py b/docs/en_us/developers/__init__.py deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/en_us/developers/requirements.txt b/docs/en_us/developers/requirements.txt deleted file mode 100644 index bf6fa8cb0d..0000000000 --- a/docs/en_us/developers/requirements.txt +++ /dev/null @@ -1,7 +0,0 @@ -path.py -Django >=1.4,<1.5 -pytz --e git+https://github.com/edx/XBlock.git#egg=XBlock -lxml -sphinxcontrib-napoleon==0.2.6 -stevedore==0.14.1 diff --git a/docs/en_us/developers/source/__init__.py b/docs/en_us/developers/source/__init__.py deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/en_us/developers/source/_static/homepage-bg.jpg b/docs/en_us/developers/source/_static/homepage-bg.jpg deleted file mode 100644 index 61da5545c1..0000000000 Binary files a/docs/en_us/developers/source/_static/homepage-bg.jpg and /dev/null differ diff --git a/docs/en_us/developers/source/_templates/layout.html b/docs/en_us/developers/source/_templates/layout.html deleted file mode 100644 index 66ff998af1..0000000000 --- a/docs/en_us/developers/source/_templates/layout.html +++ /dev/null @@ -1,5 +0,0 @@ -{% extends "!layout.html" %} - -{% block header %} -Edx logo -{% endblock %} \ No newline at end of file diff --git a/docs/en_us/developers/source/analytics.rst b/docs/en_us/developers/source/analytics.rst deleted file mode 100644 index f9502fe571..0000000000 --- a/docs/en_us/developers/source/analytics.rst +++ /dev/null @@ -1,131 +0,0 @@ -.. _analytics: - -############## -Analytics -############## - -The edX LMS and Studio are instrumented to enable tracking of metrics and events of interest. These data can be used for educational research, decision support, and operational monitoring. - -The primary mechanism for tracking events is the `Event Tracking`_ API. It should be used for the vast majority of cases. - -================= -Event Tracking -================= - -The `event-tracking`_ library aims to provide a simple API for tracking point-in-time events. The `event-tracking documentation`_ summarizes the features and primary use cases of the library as well as the current and future design intent. - -Emitting Events -***************** - -Emitting from server-side python code:: - - from eventtracking import tracker - tracker.emit('some.event.name', {'foo': 'bar'}) - -Emitting from client-side coffee script:: - - Logger.log 'some.event.name', 'foo': 'bar' - -.. note:: - The client-side API currently uses a deprecated library (the ``track`` djangoapp) instead of the event-tracking library. Eventually, event-tracking will publish a client-side API of its own: when available, that API should be used instead of the ``track``-based solution. See :ref:`deprecated_api`. - -Naming Events -============== - -Event names are intended to be formatted as `.` separated strings and help processing of related events. The structure is intended to be `namespace.object.action`. The namespace is intended to be a `.` separated string that helps identify the source of events and prevent events with similar or identical objects and actions from being confused with one another. The object is intended to be a noun describing the object that was acted on. The action is intended to be a past tense verb describing what happened. - -Examples: - - * ``edx.course.enrollment.activated`` - * Namespace: ``edx`` - * Object: ``course.enrollment`` - * Action: ``activated`` - -Choosing Events to Emit -======================== - -Consider emitting events to capture user intent. These will typically be emitted on the client side when a user -interacts with the user interface in some way. - -Consider also emitting events when models change. Most models are not append-only and it is frequently the case that an -analyst would want to see the value of a particular field at a particular moment in time. Given that many fields are -overwritten, that information is lost unless an event is emitted when the model is changed. - -Sensitive Information -===================== - -By default, event information is written to an unencrypted file on disk. Therefore, do not include clear text passwords, credit card numbers, or other similarly sensitive information. - -Size -====== - -A cursory effort to regulate the size of the event is appreciated. If an event is too large, it may be omitted from the event stream. However, do not sacrifice the clarity of an event in an attempt to minimize size. It is much more important that the event is clear. - -Debugging Events -================= - -On devstack, emitted events are stored in the ``/edx/var/log/tracking.log`` log -file. This file can be useful for validation and debugging. - -Documenting Events -******************* - -The *edX Platform Developer's Guide* provides guidelines for `Contributing to -Open edX `_. As part of your effort to add events to -the platform, consider including comments that identify the purpose of the -events and the fields emitted for them. A description can assure that -researchers and other members of the open edX community understand your intent -and use the event correctly. - -The `edX Research Guide -`_ includes reference -information for emitted events that are included in tracking logs. - -Request Context Middleware -********************************** - -The platform includes a middleware class that enriches all events emitted -during the processing of a given request with details about the request that -greatly simplify downstream processing. This is called the ``TrackMiddleware`` -and can be found in ``edx-platform/common/djangoapps/track/middleware.py``. - -Legacy Application Event Processor -********************************** - -In order to support legacy analysis applications, the platform emits standard events using ``eventtracking.tracker.emit()``. However, it uses a custom event processor which modifies the event before saving it to ensure that the event can be parsed by legacy systems. Specifically, it replicates some information so that it is accessible in exactly the same way as it was before. This state is intended to be temporary until all existing legacy systems can be altered to use the new field locations. - -======================= -Other Tracking Systems -======================= - -The following tracking systems are currently used for specialized analytics. There is some redundancy with event-tracking that is undesirable. The event-tracking library could be extended to support some of these systems, allowing for a single API to be used while still transmitting data to each of these service providers. This would reduce discrepancies between the measurements made by the various systems and significantly clarify the instrumentation. - -Data Dog -***************** - -Data dog is used primarily for real-time operational monitoring of a running edX platform server. It supports rapid display and monitoring of various metrics within the platform such as enrollments, user creation and answers to problems. - -edX platform is instrumented to send data to `data dog`_ using the standard `dogapi`_ python package. If ``lms.auth.json`` contains a ``DATADOG_API`` key whose value is a valid data dog API key, then the edX platform will transmit a variety of metrics to data dog. Running ``git grep dog_stats_api`` will give a pretty good overview of the usage of data dog to track operational metrics. - -Segment.IO -***************** - -A selection of events can be transmitted to segment.io in order to take advantage of a wide variety of analytics-related third party services such as Mixpanel and Chartbeat. It is enabled in the LMS if the ``SEGMENT_IO_LMS`` feature flag is enabled and the ``SEGMENT_IO_LMS_KEY`` key is set to a valid segment.io API key in the ``lms.auth.json`` file. - -Google Analytics -***************** - -Google analytics tracks all LMS page views. It provides several useful metrics such as common referrers and search terms that users used to find the edX web site. - -.. _deprecated_api: - -Deprecated APIs -***************** - -The ``track`` djangoapp contains a deprecated mechanism for emitting events. Direct usage of ``server_track`` is deprecated and should be avoided in new code. Old calls to ``server_track`` should be replaced with calls to ``tracker.emit()``. The celery task-based event emission and client-side event handling do not currently have a suitable alternative approach, so they continue to be supported. - -.. _event-tracking: https://github.com/edx/event-tracking -.. _event-tracking documentation: http://event-tracking.readthedocs.org/en/latest/overview.html#event-tracking -.. _data dog: http://www.datadoghq.com/ -.. _dogapi: http://pydoc.datadoghq.com/en/latest/ diff --git a/docs/en_us/developers/source/browsers.rst b/docs/en_us/developers/source/browsers.rst deleted file mode 100644 index c98836b8f7..0000000000 --- a/docs/en_us/developers/source/browsers.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../shared/browsers.rst \ No newline at end of file diff --git a/docs/en_us/developers/source/calc.rst b/docs/en_us/developers/source/calc.rst deleted file mode 100644 index 659ebc11d7..0000000000 --- a/docs/en_us/developers/source/calc.rst +++ /dev/null @@ -1,7 +0,0 @@ -******************************************* -Calc -******************************************* - -.. automodule:: calc - :members: - :show-inheritance: diff --git a/docs/en_us/developers/source/capa.rst b/docs/en_us/developers/source/capa.rst deleted file mode 100644 index be828ba33a..0000000000 --- a/docs/en_us/developers/source/capa.rst +++ /dev/null @@ -1,52 +0,0 @@ -******************************************* -Capa module -******************************************* -Contents: - -.. module:: capa - -.. toctree:: - :maxdepth: 2 - - -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/en_us/developers/source/change_log.rst b/docs/en_us/developers/source/change_log.rst deleted file mode 100644 index 9e45337be8..0000000000 --- a/docs/en_us/developers/source/change_log.rst +++ /dev/null @@ -1,25 +0,0 @@ - -********** -Change Log -********** - - -.. list-table:: - :widths: 15 75 - :header-rows: 1 - - * - Date - - Change - * - 11/07/14 - - Created the :ref:`edX Modulestores` section and added the :ref:`Split - Mongo Modulestore` chapter. - * - 06/23/14 - - Added a :ref:`Preface` with resources for course teams, developers, researchers, and students. - * - 05/20/14 - - Added the :ref:`Analytics` chapter. - * - 04/25/2014 - - Added the :ref:`Contributing to Open edX` chapter. - * - 03/28/2014 - - Added the :ref:`Custom JavaScript Applications` chapter. - - diff --git a/docs/en_us/developers/source/chem.rst b/docs/en_us/developers/source/chem.rst deleted file mode 100644 index 025c436d37..0000000000 --- a/docs/en_us/developers/source/chem.rst +++ /dev/null @@ -1,69 +0,0 @@ -******************************************* -Chemistry modules -******************************************* - -.. module:: chem - -Miller -====== - -.. automodule:: chem.miller - :members: - :show-inheritance: - -UI part and inputtypes ----------------------- -Miller module is used in the system in crystallography problems. -Crystallography is a class in :mod:`capa` inputtypes module. -It uses *crystallography.html* for rendering and **crystallography.js** -for UI part. - -Documentation from **crystallography.js**:: - - For a crystallographic problem of the type - - Given a plane definition via miller indexes, specify it by plotting points on the edges - of a 3D cube. Additionally, select the correct Bravais cubic lattice type depending on the - physical crystal mentioned in the problem. - - we create a graph which contains a cube, and a 3D Cartesian coordinate system. The interface - will allow to plot 3 points anywhere along the edges of the cube, and select which type of - Bravais lattice should be displayed along with the basic cube outline. - - When 3 points are successfully plotted, an intersection of the resulting plane (defined by - the 3 plotted points), and the cube, will be automatically displayed for clarity. - - After lotting the three points, it is possible to continue plotting additional points. By - doing so, the point that was plotted first (from the three that already exist), will be - removed, and the new point will be added. The intersection of the resulting new plane and - the cube will be redrawn. - - The UI has been designed in such a way, that the user is able to determine which point will - be removed next (if adding a new point). This is achieved via filling the to-be-removed point - with a different color. - - - -Chemcalc -======== - -.. automodule:: chem.chemcalc - :members: - :show-inheritance: - -Chemtools -========= - -.. automodule:: chem.chemtools - :members: - :show-inheritance: - - -Tests -===== - -.. automodule:: chem.tests - :members: - :show-inheritance: - - diff --git a/docs/en_us/developers/source/cms.rst b/docs/en_us/developers/source/cms.rst deleted file mode 100644 index c09043d0b7..0000000000 --- a/docs/en_us/developers/source/cms.rst +++ /dev/null @@ -1,10 +0,0 @@ -******************************************* -CMS module -******************************************* - - -.. module:: cms -.. toctree:: - - transcripts.rst - diff --git a/docs/en_us/developers/source/code-considerations.rst b/docs/en_us/developers/source/code-considerations.rst deleted file mode 100644 index e37e087881..0000000000 --- a/docs/en_us/developers/source/code-considerations.rst +++ /dev/null @@ -1,181 +0,0 @@ -******************* -Code Considerations -******************* - -This is a checklist of all of the things that we expect a developer to consider -as they are building new or modifying existing functionality. - -Operational Impact -================== - -* Are there new points in the system that require operational monitoring? - - * External system that you now depend on (Mathworks, SoftwareSecure, - CyberSource, etc...) - * New reliance on disk space? - * New stand process (workers? elastic search?) that need to always be available? - * A new queue that needs to be monitored for dequeueing - * Bulk Email --> Amazon SES, Inbound queues, etc... - * Are important feature metrics sent to datadog and is there a - dashboard to monitor them? - -* Am I building a feature that will have impact to the performance of the system? - Keep in mind that Open edX needs to support hundreds of thousands if not - millions of students, so be careful that you code will work well when the - numbers get large. - - * Deep Search - * Grade Downloads - -* Are reasonable log messages being written out for debugging purposes? -* Will this new feature easily start up in the Vagrant image? -* Do we have documentation for how to start up this feature if it has any - new startup requirements? -* Are there any special directories/file system permissions that need to be set? -* Will this have any impact to the CDN related technologies? -* Are we pushing any extra manual burden on the Operations team to have to - provision anything new when new courses launch? when new schools start? etc.... -* Has the feature been tested using a production configuration with vagrant? - -See also: :doc:`deploy-new-service` - -Documentation/Training/Support -============================== - -* Is there appropriate documentation in the context of the product for - this feature? If not, how can we get it to folks? - - * For Studio much of the documentation is in the product. - -* Is this feature big enough that we need to have a session with stakeholders - to introduce this feature BEFORE we release it? (PMs, Support, etc...) - - * Paid Certificates - -* Do I have to give some more information to the Escalation Team - so that this can be supported? -* Did you add an entry to CHANGELOG? -* Did you write/edit docstrings for all of your modules, classes, and functions? - -Development -=========== - -* Did you consider a reasonable upgrade path? -* Is this a feature that we need to slowly roll out to different audiences? - - * Bulk Email - -* Have you considered exposing an appropriate amount of configuration options - in case something happens? -* Have you considered a simple way to "disable" this feature if something is broken? - - * Centralized Logging - -* Will this feature require any security provisioning? - - * Which roles use this feature? Does it make sense to ensure that only those - roles can see this feature? - * Assets in the Studio Library - -* Did you ensure that any new libraries are added to appropriate provisioning - scripts and have been checked by OSCM for license appropriateness? -* Is there an open source alternative? -* Are we locked down to any proprietary technologies? (AWS, ...) -* Did you consider making APIs so that others can change the implementation if applicable? -* Did you consider Internationalization (I18N) and Localization (L10N)? -* Did you consider Accessibility (A11y)? -* Will your code work properly in workers? -* Have you considered the large-scale modularity of the code? For example, - xmodule and xblock should not use Django features directly. - -Testing -======= - -* Did you make sure that you tried boundary conditions? -* Did you try unicode input/data? - - * The name of the person in paid certifactes - * The name of the person in bulk email - * The body of the text in bulk email - * etc - -* Did you try funny characters in the input/data? (~!@#$%^&*()';/.,<>, etc...) -* Have you done performance testing on this feature? Do you know how much - performance is good enough? -* Did you ensure that your functionality works across all supported browsers? -* Do you have the right hooks in your HTML to ensure that the views are automatable? -* Are you ready if this feature has 10x the expected usage? -* What happens if an external service does not respond or responds with - a significant delay? -* What are possible failure modes? Do your unit tests exercise these code paths? -* Does this change affect templates and/or JavaScript? If so, are there - Selenium tests for the affected page(s)? Have you tested the affected - page(s) in a sandbox? - -Analytics -========= - -* Are learning analytics events being recorded in an appropriate way? - - * Do your events use a descriptive and uniquely enough event type and - namespace? - * Did you ensure that you capture enough information for the researchers - to benefit from this event information? - * Is it possible to reconstruct the state of your module from the history - of its events? - * Has this new event been documented so that folks downstream know how - to interpret it? - * Are you increasing the amount of logging in any major way? - -* Are you sending appropriate/enough information to MixPanel, - Google Analytics, Segment IO? - -Collaboration -============= -* Are there are other teams that would benefit from knowing about this feature? - - * Forums/LMS - email - -* Does this feature require a special broadcast to external teams as well? - -Open Source -=========== -* Can we get help from the community on this feature? -* Does the community know enough about this? - -UX/Design/Front End Development -=============================== -* Did you make sure that the feature is going to pass - Accessibility requirements (still TBD)? -* Did you make sure any system/instructional text is I18N ready? -* Did you ensure that basic functionality works across all supported browsers? -* Did you plan for the feature's UI to degrade gracefully (or be - progressively enhanced) based on browser capability? -* Did you review the page/view under all browser/agent conditions - - viewport sizes, images off, css off? -* Did you write any HTML with ideal page/view semantics in mind? -* When writing HTML, did you adhere to standards/conventions around class/id names? -* When writing Sass, did you follow OOCSS/SMACSS philosophy ([1]_, [2]_, [3]_), - variable/extend organization and naming conventions, and UI abstraction conventions? -* When writing Sass, did you document any new variables, - extend-based classes, or mixins? -* When writing/adding JavaScript, did you consider the asset pipeline - and page load timeline? -* When writing JavaScript, did you note what code is for prototyping vs. production? -* When adding new templates, views, assets (Sass, images, plugins/libraries), - did you follow existing naming and file architecture conventions? -* When adding new templates, views, assets (Sass, images, plugins/libraries), - did you add any needed documentation? -* Did you use templates and good Sass architecture to keep DRY? -* Did we document any aspects about the feature (flow, purpose, intent) - that we or other teams will need to know going forward? - -.. [1] http://smacss.com/ -.. [2] http://thesassway.com/intermediate/avoid-nested-selectors-for-more-modular-css -.. [3] http://ianstormtaylor.com/oocss-plus-sass-is-the-best-way-to-css/ - -edX.org Specific -================ - -* Ensure that you have not broken import/export? -* Ensure that you have not broken video player? (Lyla video) diff --git a/docs/en_us/developers/source/common-lib.rst b/docs/en_us/developers/source/common-lib.rst deleted file mode 100644 index 1cdae8c76b..0000000000 --- a/docs/en_us/developers/source/common-lib.rst +++ /dev/null @@ -1,16 +0,0 @@ -Common / lib -=============================== -Contents: - -.. toctree:: - :maxdepth: 2 - - xmodule.rst - modulestore.rst - capa.rst - chem.rst - sandbox-packages.rst - symmath.rst - calc.rst - opaque-keys.rst - diff --git a/docs/en_us/developers/source/conf.py b/docs/en_us/developers/source/conf.py deleted file mode 100644 index 8751e46de1..0000000000 --- a/docs/en_us/developers/source/conf.py +++ /dev/null @@ -1,237 +0,0 @@ -# -*- coding: utf-8 -*- -# pylint: disable=invalid-name -# pylint: disable=redefined-builtin -# pylint: disable=protected-access -# pylint: disable=unused-argument - -import os -from path import path -import sys - -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' - - -sys.path.append('../../../../') - -from docs.shared.conf import * - - -# Add any paths that contain templates here, relative to this directory. -templates_path.append('source/_templates') - - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path.append('source/_static') - -if not on_rtd: # only import and set the theme if we're building docs locally - import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - - -# 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. -root = path('../../../..').abspath() -sys.path.insert(0, root) - -sys.path.append(root / "common/djangoapps") -sys.path.append(root / "common/lib") -sys.path.append(root / "common/lib/capa") -sys.path.append(root / "common/lib/chem") -sys.path.append(root / "common/lib/sandbox-packages") -sys.path.append(root / "common/lib/xmodule") -sys.path.append(root / "common/lib/opaque_keys") -sys.path.append(root / "lms/djangoapps") -sys.path.append(root / "lms/lib") -sys.path.append(root / "cms/djangoapps") -sys.path.append(root / "cms/lib") -sys.path.insert( - 0, - os.path.abspath( - os.path.normpath( - os.path.dirname(__file__) + '/../../../' - ) - ) -) -sys.path.append('.') - -# django configuration - careful here -if on_rtd: - os.environ['DJANGO_SETTINGS_MODULE'] = 'lms' -else: - os.environ['DJANGO_SETTINGS_MODULE'] = 'lms.envs.test' - - -# -- General configuration ----------------------------------------------------- - -# 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', 'sphinxcontrib.napoleon'] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['build'] - - -# Output file base name for HTML help builder. -htmlhelp_basename = 'edXDocs' - -project = u'edX Platform Developer Documentation' -copyright = u'2014, edX' - -# --- Mock modules ------------------------------------------------------------ - -# Mock all the modules that the readthedocs build can't import - - -class Mock(object): - def __init__(self, *args, **kwargs): - pass - - def __call__(self, *args, **kwargs): - return Mock() - - @classmethod - def __getattr__(cls, name): - if name in ('__file__', '__path__'): - return '/dev/null' - elif name[0] == name[0].upper(): - mockType = type(name, (), {}) - mockType.__module__ = __name__ - return mockType - else: - return Mock() - -# The list of modules and submodules that we know give RTD trouble. -# Make sure you've tried including the relevant package in -# docs/share/requirements.txt before adding to this list. -MOCK_MODULES = [ - 'bson', - 'bson.errors', - 'bson.objectid', - 'dateutil', - 'dateutil.parser', - 'fs', - 'fs.errors', - 'fs.osfs', - 'lazy', - 'mako', - 'mako.template', - 'matplotlib', - 'matplotlib.pyplot', - 'mock', - 'numpy', - 'oauthlib', - 'oauthlib.oauth1', - 'oauthlib.oauth1.rfc5849', - 'PIL', - 'pymongo', - 'pyparsing', - 'pysrt', - 'requests', - 'scipy.interpolate', - 'scipy.constants', - 'scipy.optimize', - 'yaml', - 'webob', - 'webob.multidict', -] - -if on_rtd: - for mod_name in MOCK_MODULES: - sys.modules[mod_name] = Mock() - -# ----------------------------------------------------------------------------- - -# from http://djangosnippets.org/snippets/2533/ -# autogenerate models definitions - -import inspect -import types -from HTMLParser import HTMLParser - - -def force_unicode(s, encoding='utf-8', strings_only=False, errors='strict'): - """ - Similar to smart_unicode, except that lazy instances are resolved to - strings, rather than kept as lazy objects. - - If strings_only is True, don't convert (some) non-string-like objects. - """ - if strings_only and isinstance(s, (types.NoneType, int)): - return s - if not isinstance(s, basestring,): - if hasattr(s, '__unicode__'): - s = unicode(s) - else: - s = unicode(str(s), encoding, errors) - elif not isinstance(s, unicode): - s = unicode(s, encoding, errors) - return s - - -class MLStripper(HTMLParser): - def __init__(self): - self.reset() - self.fed = [] - - def handle_data(self, d): - self.fed.append(d) - - def get_data(self): - return ''.join(self.fed) - - -def strip_tags(html): - s = MLStripper() - s.feed(html) - return s.get_data() - - -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 - - # 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__)) - return lines - - -def setup(app): - """Setup docsting processors""" - #Register the docstring processor with sphinx - app.connect('autodoc-process-docstring', process_docstring) diff --git a/docs/en_us/developers/source/deploy-new-service.rst b/docs/en_us/developers/source/deploy-new-service.rst deleted file mode 100644 index 7cab9d0cd3..0000000000 --- a/docs/en_us/developers/source/deploy-new-service.rst +++ /dev/null @@ -1,133 +0,0 @@ -*********************************** -So You Want to Deploy a New Service -*********************************** - -Intro -===== - -This page is a work-in-progress aimed at capturing all the details needed to -deploy a new service in the edX environment. - -Considerations -============== - -What Does Your Service Do -------------------------- -Understanding how your service works and what it does helps Ops support -the service in production. - -Sizing and Resource Profile ---------------------------- -What class of machine does your service require. What resources are most -likely to be bottlenecks for your service, CPU, memory, bandwidth, something else? - -Customers ---------- -Who will be consuming your service? What is the anticipated initial usage? -What factors will cause usage to grow? How many users can your service support? - -Code ----- -What repository or repositories does your service require. -Will your service be deployed from a non-public repo? - -Ideally your service should follow the same release management process as the LMS. -This is documented in the wiki, so please ensure you understand that process in depth. - -Was the service code reviewed? - -Settings --------- -How does your service read in environment specific settings? Were all -hard-coded references to values that should be settings, e.g., database URLs -and credentials, message queue endpoints, etc., found and resolved during -code review? - -License -------- -Is the license included in the repo? - -How does your service run -------------------------- -Is it HTTP based? Does it run periodically? Both? - -Persistence ------------ -Ops will need to know the following things: - -* What persistence needs does you service have - - * Will it connect to an existing database? - * Will it connect to Mongo - -* What are the least permissive permissions your service needs to do its job. - -Logging -------- - -It's important that your application logging in built out to provide sufficient -feedback for problem determination as well as ensuring that it is operating as -desired. It's also important that your service log using our deployment -standards, i.e., logs vs syslog in deployment environments and utilizes the -standard log format for syslog. Can the logs be consumed by Splunk? They -should not be if they contain data discussed in the Data Security section below. - -Metrics -------- -What are the key metrics for your application? Concurrent users? -Transactions per second? Ideally you should create a DataDog view that -captures the key metrics for your service and provided an instant gauge of -overally service health. - -Messaging ---------- -Does your service need to access a message queue. - -Email ------ -Does your service need to send email - -Access to Other Service ------------------------ -Does your service need access to other service either within or -outside of the edX environment. Some example might be, the comment service, -the LMS, YouTube, s3 buckets, etc. - -Service Monitoring ------------------- -Your service should have a facility for remote monitoring that has the -following characteristics: - -* It should exercise all the components that your service requires to run successfully. -* It should be necessary and sufficient for ensuring your service is healthy. -* It should be secure. -* It should not open your service to DDOS attacks. - -Fault Tolerance and Scalability -------------------------------- -How can your application be deployed to ensure that it is fault tolerant -and scalable? - -Network Access --------------- -From where should your service be accessible. - -Data Security -------------- -Will your application be storing or handling data in any of the -following categories: - -* Personally Identifiable Information in General, e.g., user's email addresses. -* Tracking log data -* edX confidential data - -Testing -------- -Has your service been load tested? What there the details of the test. -What determinations can we make regarding when we will need to scale if usage -trend upward? How can ops exercise your service in order to tests end-to-end -integration. We love no-op-able tasks. - -Additional Requirements ------------------------ -Anything else we should know about. diff --git a/docs/en_us/developers/source/djangoapps-common.rst b/docs/en_us/developers/source/djangoapps-common.rst deleted file mode 100644 index 0d67dfd591..0000000000 --- a/docs/en_us/developers/source/djangoapps-common.rst +++ /dev/null @@ -1,54 +0,0 @@ -******************************************* -Common -******************************************* - -.. module:: common.djangoapps - -Student -======= - -.. automodule:: student - :members: - :show-inheritance: - -Models ------- - -.. automodule:: student.models - :members: - :show-inheritance: - -Views ------ - -.. automodule:: student.views - :members: - :show-inheritance: - -Admin ------ - -.. automodule:: student.admin - :members: - :show-inheritance: - -Tests ------ - -.. automodule:: student.tests - :members: - :show-inheritance: - -Management ----------- - -.. automodule:: student.management - :members: - :show-inheritance: - -Migrations ----------- - -.. automodule:: student.migrations - :members: - :show-inheritance: \ No newline at end of file diff --git a/docs/en_us/developers/source/djangoapps.rst b/docs/en_us/developers/source/djangoapps.rst deleted file mode 100644 index 7a8414189a..0000000000 --- a/docs/en_us/developers/source/djangoapps.rst +++ /dev/null @@ -1,10 +0,0 @@ -Django applications -=============================== -Contents: - -.. toctree:: - :maxdepth: 2 - - lms.rst - cms.rst - djangoapps-common.rst \ No newline at end of file diff --git a/docs/en_us/developers/source/experiments.rst b/docs/en_us/developers/source/experiments.rst deleted file mode 100644 index 8ac2caefe9..0000000000 --- a/docs/en_us/developers/source/experiments.rst +++ /dev/null @@ -1,76 +0,0 @@ -******************************************* -Content experiments -******************************************* - -This is a brief overview of the support for content experiments in the platform. - -For now, there is only one type of experiment: content split testing. This lets course authors define an experiment with several *experimental conditions*, add xblocks that reference that experiment in various places in the course, and specify what content students in each experimental condition should see. The LMS provides a way to randomly assign students to experimental conditions for each experiment, so that they see the right content at runtime. - -Experimental conditions are essentially just a set of groups to partition users into. This may be useful to other non-experiment uses, so the implementation is done via a generic UserPartition interface. Copying the doc string, a UserPartition is: - - A named way to partition users into groups, primarily intended for running - experiments. It is expected that each user will be in at most one group in a - partition. - - A Partition has an id, name, description, and a list of groups. - The id is intended to be unique within the context where these are used. (e.g. for - partitions of users within a course, the ids should be unique per-course) - -There is an XModule helper library ``partitions_service`` that helps manage user partitions from XBlocks (at the moment just from the split_test module). It provides an interface to store and retrieve the groups a user is in for particular partitions. - -User assignments to particular groups within a partition must be persisted. This is done via a User Info service provided by the XBlock runtime, which exposes a generic user tagging interface, allowing storing key-value pairs for the user scoped to a particular course. - -UserPartitions are configured at the course level (makes sense in Studio, for author context, and there's no XBlock scope to store per-course configuration state), and currently exposed via the LMS XBlock runtime as ``runtime.user_partitions``. - -More details on the components below. - - -User metadata service ---------------------- - -Goals: provide a standard way to store information about users, to be used e.g. by XBlocks, and make that information easily accessible when looking at analytics. - -When the course context is added to the analytics events, it should add the user's course-specific tags as well. -When the users global context is added to analytics events, it should add the user's global tags. - -We have a ``user_api`` app, which has REST interface to "User Preferences" for global preferences, and now a ``user_service.py`` interface that exposes per-course tags, with string keys (<=255 chars) and arbitrary string values. The intention is that the values are fairly short, as they will be included in all analytics events about this user. - -The XBlock runtime includes a ``UserServiceInterface`` mixin that provides access to this interface, automatically filling in the current user and course context. This means that with the current design, an XBlock can't access tags for other users or from other courses. - -To avoid name collisions in the keys, we rely on convention. e.g. the XBlock partition service uses ``'xblock.partition_service.partition_{0}'.format(user_partition.id)``. - - - -Where the code is: ----------------- - - -common: - -- partitions library--defines UserPartitions, provides partitions_service API. -- split_test_module -- a block that has one child per experimental condition (could be a vertical or other container with more blocks inside), and config specifying which child corresponds to which condition. -- course_module -- a course has a list of UserPartitions, each of which specifies the set of groups to divide users into. - -LMS: - -- runtime--LmsUserPartitions, UserServiceMixin mixins. Provides a way for the partition_service to get the list of UserPartitions defined in a course, and get/set per-user tags within a course scope. -- user_api app -- provides persistence for the user tags. - -Things to watch out for (some not implemented yet): -------------------------------------------- - -- grade export needs to be smarter, because different students can see different graded things -- grading needs to only grade the children that a particular student sees (so if there are problems in both conditions in a split_test, any student would see only one set) -- ui -- icons in sequences need to be passed through - - tooltips need to be passed through -- author changes post-release: conditions can be added or deleted after an experiment is live. This is usually a bad idea, but can be useful, so it's allowed. Need to handle all the cases. -- analytics logging needs to log all the user tags (if we really think it's a good idea). We'll probably want to cache the tags in memory for the duration of the request, being careful that they may change as the request is processed. -- need to add a "hiding" interface to XBlocks that verticals, sequentials, and courses understand, to hide children that set it. Then give the split test module a way to say that particular condition should be empty and hidden, and pass that up. -- staff view should show all the conditions, clearly marked - -Things to test: - - randomization - - persistence - - correlation between test that use the same groups - - non-correlation between tests that use different groups - diff --git a/docs/en_us/developers/source/extending_platform/extending.rst b/docs/en_us/developers/source/extending_platform/extending.rst deleted file mode 100644 index e9bba048a7..0000000000 --- a/docs/en_us/developers/source/extending_platform/extending.rst +++ /dev/null @@ -1,89 +0,0 @@ - -.. _Options for Extending the edX Platform: - -########################################## -Options for Extending the edX Platform -########################################## - -There are several options for extending the Open edX Platform to provide useful -and innovative educational content in your courses. - -This section of the developers' documentation lists and explains the different ways to extend the platform, starting with the following table. Click the name of the extension type in the column header for more information. - -.. list-table:: - :widths: 10 10 10 10 10 10 - :header-rows: 1 - - * - - - :ref:`Custom JavaScript Applications` - - LTI - - External Graders - - XBlocks - - Platform Customization - * - Development Cost - - Low - - Low - - Medium - - Medium - - High - * - Language - - JavaScript - - Any - - Any - - Python - - Python - * - Development Environment Needed - - No - - No - - Yes - - Yes - - Yes - * - Self-hosting Needed - - No - - Yes - - Yes - - No - - No - * - Need edX Involvement - - No - - No - - Yes - - Yes - - Yes - * - Clean UI Integration - - Yes - - No (see LTI) - - Yes - - Yes - - Yes - * - Mobile enabled - - Possibly - - Possibly - - Yes - - Yes - - Yes - * - Server Side Grading - - Possibly (See JavaScript) - - Yes - - Yes - - Yes - - Yes - * - Usage Data - - No (See JavaScript) - - No - - Limited - - Yes - - Yes - * - Provision in Studio - - No - - No - - No - - Yes - - No - * - Privacy Loss Compared to Hosting Open edX - - No - - Possibly - - Possibly - - No - - No - diff --git a/docs/en_us/developers/source/extending_platform/index.rst b/docs/en_us/developers/source/extending_platform/index.rst deleted file mode 100644 index 5df61fbcc9..0000000000 --- a/docs/en_us/developers/source/extending_platform/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -########################### -Extending the edX Platform -########################### - -.. toctree:: - :maxdepth: 2 - - extending.rst - javascript - js_template_example \ No newline at end of file diff --git a/docs/en_us/developers/source/extending_platform/javascript.rst b/docs/en_us/developers/source/extending_platform/javascript.rst deleted file mode 100644 index 3d883259f8..0000000000 --- a/docs/en_us/developers/source/extending_platform/javascript.rst +++ /dev/null @@ -1,315 +0,0 @@ -.. _Custom JavaScript Applications: - -########################################## -Custom JavaScript Applications -########################################## - - -******************************* -Overview -******************************* - - -You can include custom JavaScript applications (also called custom JavaScript -problems or JS Input problems) in a course. You add the application directly -into edX Studio. - -When you create a JavaScript application, Studio embeds the problem in an inline -frame (HTML ``iframe`` tag) so that students can interact with it in the LMS. - -See the following sections for more information: - -* `Grading Options for Custom JavaScript Applications`_ -* `Use a JavaScript Application Without Grading`_ -* `Use a JavaScript Application for a Summative Assessment`_ -* `Grade the Student Response with Python`_ -* `XML for Custom JavaScript Applications`_ - -See :ref:`The Custom JavaScript Display and Grading Example Template` for -information about the template application built in to edX Studio. - -Course staff should see the following sections of the document `Building and Running an edX Course `_: - -* `Custom JavaScript Display and Grading `_ - -* `Establishing a Grading Policy `_ - -The rest of this section provides more information for developers who are -creating JavaScript applications for courses on the edX platform. - -.. note:: This section assumes proficiency with JavaScript and with how problems - are constructed in edX Studio. If you intend to grade students' interactions - with your JavaScript application, you must also be proficient with Python. - - - -******************************************************* -Grading Options for Custom JavaScript Applications -******************************************************* - -When using a JavaScript application in your course content, you have three -options: - -#. A JavaScript application that visually demonstrates a concept or process. The - application would not require student interaction, and students would not be - graded. - -#. A JavaScript application that requires student interaction but does not grade - performance. Referred to as a formative assessment, such an application - provides feedback to students based on their interactions. - -#. A JavaScript application that requires and grades student interaction. - Referred to as a summative assessment, such an application can be used to - evaluate student learning against a standard. To use the JavaScript - application as a summative assessment and have student performance integrated - into the edX grading system, you must also use basic Python code in the - component. - -These options are explained through examples below. - -******************************************************* -Use a JavaScript Application Without Grading -******************************************************* - -The simplest option is to use JavaScript to show content to students, and -optionally to provide feedback as a formative assessment. - -#. In edX Studio, upload an HTML file that contains the JavaScript you want to - show students. -#. Copy the **Embed URL** of the file. -#. `Create a Custom JavaScript Display and Grading Problem `_. The template - for the problem contains the definition for a sample JavaScript application - that requires and grades student interaction. -#. Edit the XML of the component to remove grading information and refer to the - HTML file you uploaded: - -.. code-block:: xml - - - - - -For example: - -.. code-block:: xml - - - - - - -************************************************************** -Use a JavaScript Application for a Summative Assessment -************************************************************** - -To use a JavaScript Application for a summative assessment and have student -results calculated by the edX grading system, you must: - -* Include required functions in the JavaScript application. - - * `getState() Function`_ - * `setState() Function`_ - * `getGrade() Function`_ - -* Reference functions in the problem XML. - -* `Grade the Student Response with Python`_. - - -==================== -getState() Function -==================== - -Your application must contain a ``getState()`` function that returns the state -of all objects as a JSON string. - -The ``getState()`` function retrieves the state of objects in the application, -so each student experiences that application in its initial or last saved state. - -The name of the ``getState()`` function must be the value of the ``get_statefn`` -attribute of the ``jsinput`` element for the problem. - -For example: - -.. code-block:: xml - - - - - - - - . . . . - - - -******************************************************* -XML for Custom JavaScript Applications -******************************************************* - -The problem component XML that you define in Studio to provide students with a -JavaScript application has the following structure: - -.. code-block:: - - - - - - - - - - -=================== -jsinput attributes -=================== - -The following table describes the attributes of the ``jsinput`` element. - -.. list-table:: - :widths: 10 50 10 - :header-rows: 1 - - * - Attribute - - Description - - Example - * - gradefn - - The function in your JavaScript application that returns the state of the - objects to be evaluated as a JSON string. - - ``JSObject.getGrade`` - * - get_statefun - - The function in your JavaScript application that returns the state of the - objects. - - ``JSObject.getState`` - * - set_statefun - - The function in your JavaScript application that saves the state of the - objects. - - ``JSObject.setState`` - * - initial_state - - A JSON string representing the initial state, if any, of the objects. - - '{"selectedObjects":{"cube":true,"cylinder":false}}' - * - width - - The width of the IFrame in which your JavaScript application will be - displayed, in pixels. - - 400 - * - height - - The height of the IFrame in which your JavaScript application will be - displayed, in pixels. - - 400 - * - html_file - - The name of the HTML file containing your JavaScript application that - will be loaded in the IFrame. - - /static/webGLDemo.html - * - sop - - The same-origin policy (SOP), meaning that all elements have the same - protocol, host, and port. To bypass the SOP, set to ``true``. - - false diff --git a/docs/en_us/developers/source/extending_platform/js_template_example.rst b/docs/en_us/developers/source/extending_platform/js_template_example.rst deleted file mode 100644 index 1287eae492..0000000000 --- a/docs/en_us/developers/source/extending_platform/js_template_example.rst +++ /dev/null @@ -1,195 +0,0 @@ -.. _The Custom JavaScript Display and Grading Example Template: - -########################################################### -The Custom JavaScript Display and Grading Example Template -########################################################### - -As referred to in `course staff documentation `_, there is a built-in template in edX Studio that uses a sample JavaScript application. - -This sample application has students select two different shapes, a cone and a -cube. The correct state is when the cone is selected and the cube is not -selected: - -.. image:: ../images/JavaScriptInputExample.png - :alt: Image of the sample JavaScript application, with the cone selected - -You can `download files for that application `_. -You must upload these files in Studio to use them in a problem. - -The following information steps through this example to demonstrate how to apply -the guidelines in `Custom JavaScript Display and Grading`. - - -**************************** -Example getState() Function -**************************** - -In the example, the ``state`` variable is initialized for the cylinder and cube -in the ``WebGLDemo.js`` file: - -.. code-block:: javascript - - var state = { - 'selectedObjects': { - 'cylinder': false, - 'cube': false - } - } - -User interactions toggle the ``state`` values of the cylinder and cube between -``true`` and ``false``. - -The ``getState()`` function in the sample application returns the state as a -JSON string: - -.. code-block:: javascript - - function getState() { - return JSON.stringify(state); - } - - -****************************** -Example setState() Function -****************************** - -In the example, when a student clicks **Check**, the ``state`` variable is saved -so that the student can later return to the application and find it in the same -state: - -.. code-block:: javascript - - function setState() { - stateStr = arguments.length === 1 ? arguments[0] : arguments[1]; - state = JSON.parse(stateStr); - updateMaterials(); - } - -The ``updateMaterials()`` function called by ``setState()`` updates the state of -the cylinder and cone with the user's current selections: - -.. code-block:: javascript - - function updateMaterials() { - if (state.selectedObjects.cylinder) { - cylinder.material = selectedMaterial; - } - else { - cylinder.material = unselectedMaterial; - } - - if (state.selectedObjects.cube) { - cube.material = selectedMaterial; - } - else { - cube.material = unselectedMaterial; - } - } - -****************************** -Example getGrade() function -****************************** - -In the example, when a student clicks **Check**, the ``getGrade()`` function in -returns the selected objects: - -.. code-block:: javascript - - function getGrade() { - return JSON.stringify(state['selectedObjects']); - } - -The returned JSON string is then used by the Python code defined in the problem -to determine if correct objects were selected or not, and to return a result. - -******************************* -Grade the Student Response -******************************* - - -The following is the Python function ``vglcfn`` in the sample application: - -.. code-block:: python - - - -The ``ans`` parameter contains the JSON string returned by ``getGrade()``. The -value is converted to a Python Unicode structure in the variable ``par``. - -In the function's first option, object(s) the student selected are stored in the -``answer`` variable. If the student selected the cylinder and not the cube, the -``answer`` variable contains only ``cylinder``, and the function returns -``True``, which signifies a correct answer. Otherwise, it returns ``False`` and -the answer is incorrect. - -In the function's second option, the objects' states are retrieved. If the -cylinder is selected and not the cube, the function returns ``True``, which -signifies a correct answer. Otherwise, it returns ``False`` and the answer is -incorrect. - - -******************************* -XML Problem Structure -******************************* - -The XML problem for the sample template is: - -.. code-block:: xml - - - -

- The shapes below can be selected (yellow) or unselected (cyan). - Clicking on them repeatedly will cycle through these two states. -

-

- If the cone is selected (and not the cube), a correct answer will be - generated after pressing "Check". Clicking on either "Check" or "Save" - will register the current state. -

- - - - \ No newline at end of file diff --git a/docs/en_us/developers/source/i18n.rst b/docs/en_us/developers/source/i18n.rst deleted file mode 100644 index 5028dc950c..0000000000 --- a/docs/en_us/developers/source/i18n.rst +++ /dev/null @@ -1,589 +0,0 @@ -###################################### -Internationalization coding guidelines -###################################### - -Preparing code to be presented in many languages can be complex and difficult. -The rules here give the best practices for marking English strings in source -so that it can be extracted, translated, and presented to the user in the -language of their choice. - -See also: - -* `Django Internationalization `_ (overview) -* `Django: Internationalizing Python code `_ -* `Django Translation guidelines `_ -* `Django Format localization `_ - -Presented in this document are the following sections: - -* `General internationalization rules`_ -* `Editing source files`_ -* `Coverage testing`_ -* `Style guidelines`_ - - -General internationalization rules -********************************** - -In order to localize source files, we need to prepare them so that the -human-readable strings can be extracted by a pre-processing step, and then have -localized strings used at runtime. This requires attention to detail, and -unfortunately limits what you can do with strings in the code. In general: - -1. Always mark complete sentences for translation. If you combine fragments at - runtime, there is no way for the translator to construct a proper sentence - in their language. - -2. Don't join strings together at runtime to create sentences. - -3. Limit the amount of text in strings that is not presented to the user. HTML - markup is better applied after the translation. If you give HTML to the - translators, there's a good chance they will translate your tags or - attributes. - -4. Use placeholders with descriptive names: ``"Welcome {student_name}"`` is - much better than ``"Welcome {0}"``. - -See the detailed Style Guidelines at the end for details. - - -Editing source files -******************** - -While editing source files (including Python, JavaScript, or HTML template -files), use the appropriate conventions. There are a few things to know how to -do: - -1. What has to be at the top of the file (if anything) to prepare it for i18n. - -2. How are strings marked for internationalization? This takes the form of a - function call with the string as an argument. - -3. How are translator comments indicated? These are comments in the file that - will travel with the strings to the translators, giving them context to - produce the best translation. They have a "Translators:" marker. They must - appear on the line preceding the text they describe. Multi-line comments - are supported for Python in case the translator comment needs to be wrapped. - -The code samples below show how to do each of these things for: - -* `Python source code`_ -* `Django template files`_ -* `Mako template files`_ -* `JavaScript files`_ -* `Coffeescript files`_ -* `Underscore template files`_ -* `Other kinds of code`_ - -Note that you have to take into account not just the programming language involved, -but the type of file: JavaScript embedded in an HTML Mako template is treated differently -than JavaScript in a pure .js file. - -Python source code -================== - -.. highlight:: python - -In most Python source code (read the Django docs for more details):: - - from django.utils.translation import ugettext as _ - - # Translators: This will help the translator - message = _("Welcome!") - - # Translators: This is a very long comment that needs to wrap - # over multiple lines because it would be too long otherwise. - message = _("Hello world") - -Some edX code cannot use Django imports. To maintain portability, XBlocks, -XModules, Inputtypes and Responsetypes forbid importing Django. Each of these -has its own way of accessing translations. You'll use lines like these -instead:: - - ### for XBlock & XModule: - _ = self.runtime.service(self, "i18n").ugettext - # Translators: a greeting to newly-registered students. - message = _("Welcome!") - - # for InputType and ResponseType: - _ = self.capa_system.i18n.ugettext - # Translators: a greeting to newly-registered students. - message = _("Welcome!") - -"Translators" comments will work in these places too, so don't be shy about -providing clarifying comments to the translators. - - -Django template files -===================== - -.. highlight:: django - -In Django template files (`templates/*.html`):: - - {% load i18n %} - - {# Translators: this will help the translator. #} - {% trans "Welcome!" %} - -Mako template files -=================== - -.. highlight:: mako - -In Mako template files (`templates/*.html`), you can use all of the tools -available to python programmers. Just make sure to import the relevant -functions first. Here's a Mako template example:: - - <%! from django.utils.translation import ugettext as _ %> - - ## Translators: message to the translator - ${_("Welcome!")} - -JavaScript files -================ - -.. highlight:: javascript - -In order to internationalize JavaScript, first the HTML template (base.html) -must load a special JavaScript library (and Django must be configured to serve -it):: - - - -Then, in JavaScript files (`*.js`):: - - // Translators: this will help the translator. - var message = gettext('Welcome!'); - -Note that JavaScript embedded in HTML in a Mako template file is handled -differently. There, you use the Mako syntax even within the JavaScript. - -Coffeescript files -================== - -.. highlight:: coffeescript - -Coffeescript files are compiled to JavaScript files, so it works mostly like -JavaScript:: - - `// Translators: this will help the translator.` - message = gettext('Hey there!') - # Interpolation has to be done in JavaScript, not Coffeescript: - message = gettext("Error getting student progress url for '<%= student_id %>'.") - full_message = _.template(message, {student_id: unique_student_identifier}) - -But because we extract strings from the compiled .js files, there are some -native Coffeescript features that break the extraction from the .js files: - -1. You cannot use Coffeescript string interpolation: This results in string - concatenation in the .js file, so string extraction won't work. - -2. You cannot use Coffeescript comments for translator comments, since they are - not passed through to the JavaScript file. - -:: - - # NO NO not like this: - # Translators: this won't get to the translators! - message = gettext("Welcome, #{student_name}!") # This won't work! - - # YES like this: - `// Translators: this will get to the translators.` - message = gettext("This works") - - ### - Translators: This will work, but takes three lines :( - ### - message = gettext("Hey there") - -.. highlight:: python - -Underscore template files -========================= - -Underscore template files are used in conjunction with JavaScript, and so the -same techniques are used for localization. Ensure that the i18n JavaScript -library has already been loaded, and then use the regular i18n functions -such as ``gettext`` and ``interpolate`` from your template. - -For example:: - - <%- - interpolate( - gettext('This post is visible only to %(group_name)s.'), - {group_name: group.group_name}, - true - ) - %> - -Note: it is recommended that you use ``<%-`` for all translated strings -as this will HTML escape the string before including it in the page. This -ensures that translations are free to use non-HTML characters. - -Other kinds of code -=================== - -We have not yet established guidelines for internationalizing the following. - -* Course content (such as subtitles for videos) - -* Documentation (written for Sphinx as .rst files) - - -Building and testing your code -****************************** - -These instructions assume you are a developer writing new code to check in to -Github. For other use cases in the translation life cycle (such as translating -the strings, or checking the translations into Github, see use cases). - -1. Create human-readable .po files with the latest strings. This command may - take a minute or two to complete:: - - $ cd edx-platform - $ paver i18n_extract - -2. Generate dummy strings: See coverage testing (below) for more details. This - will create an "Esperanto" translation that is actually over-accented - English. Use this to create fake translations:: - - $ paver i18n_dummy - -3. Run the paver i18n_generate command to create machine-readable .mo files:: - - $ paver i18n_generate - -4. Django should be ready to go. The next time you run Studio or LMS, append - ``?preview-lang=eo`` to the URL to turn on Esperanto as a dark language. The - accented-English strings (from step 3, above) should be displayed. - - If you experience issues, be sure that your settings for ``USE_I18N`` and - ``USE_L10N`` are both set to True. - -5. With Esperanto turned on as a dark language (see Step 4), review the pages - affected by your code and verify that you see fake translations. If you see - plain English instead, your code is not being properly translated. Review - the steps in editing source files (above). - -6. When you are done reviewing, append ``?clear-lang`` to the LMS or Studio URL - to reset your session to English. - - -Coverage testing -**************** - -This tool is used during the bootstrap phase, when presumably (1) there is a -lot of edX source code to be converted, and (2) there are not a lot of -available translations for externalized edX strings. At the end of the -bootstrap phase, we will eventually deprecate this tool in favor of other -processes. Once most of the edX source code has been successfully converted, -and there are several full translations available, it will be easier to detect -and correct specific gaps in compliance. - -Use the coverage tool to generate dummy files:: - - $ paver i18n_dummy - -This will create new dummy translations in the Esperanto directory -(edx-platform/conf/local/eo/LC_MESSAGES). - -You can then configure your browser preferences to view Esperanto as your -preferred language. Instead of plain English strings, you should see something -like this: - - Thé Fütüré øf Ønlïné Édüçätïøn Ⱡσяєм ι# - Før änýøné, änýwhéré, änýtïmé Ⱡσяєм # - -This dummy text is distinguished by extra accent characters. If you see plain -English instead (without these accents), it most likely means the string has -not been externalized yet. To fix this: - -* Find the string in the source tree (either in Python, JavaScript, or HTML - template code). - -* Refer to the above coding guidelines to make sure it has been externalized - properly. - -* Rerun the scripts and confirm that the strings are now properly converted - into dummy text. - -This dummy text is also distinguished by Lorem ipsum text at the end of each -string, and is always terminated with "#". The original English string is -padded by about 30% extra characters, to simulate some language (like German) -which tend to have longer strings than English. If you see problems with your -page layout, such as columns that don't fit, or text that is truncated (the -``#`` character should always be displayed on every string), then you will -probably need to fix the page layouts accordingly to accommodate the longer -strings. - - -Style guidelines -**************** - -Don't append strings, interpolate values -======================================== - -It is harder for translators to provide reasonable translations of small -sentence fragments. If your code appends sentence fragments, even if it seems -to work OK for English, the same concatenation is very unlikely to work -properly for other languages. - -Bad:: - - message = _("The directory has ") + len(directory.files) + _(" files.") - -In this scenario, the translator will have to figure out how to translate these -two separate strings. It is very difficult to translate a fragment like "The -directory has." In some languages the fragments will be in different order. For -example, in Japanese, "files" will come before "has." - -It is much easier for a translator to figure out how to translate the entire -sentence, using the pattern "The directory has {file_count} files." - -Good:: - - message = _("The directory has {file_count} files.").format(file_count=directory.files) - - -Use named placeholders -====================== - -Python string formatting provides both positional and named placeholders. Use -named placeholders, never use positional placeholders. Positional placeholders -can't be translated into other languages which may need to re-order them to -make syntactically correct sentences. Even with a single placeholder, a named -placeholder provides more context to the translator. - -Bad:: - - message = _('Today is %s %d.') % (m, d) - -OK:: - - message = _('Today is %(month)s %(day)s.') % {'month': m, 'day': d} - -Best:: - - message = _('Today is {month} {day}.').format(month=m, day=d) - -Notice that in English, the month comes first, but in Spanish the day comes -first. This is reflected in the .po file like this:: - - # fragment from edx-platform/conf/locale/es/LC_MESSAGES/django.po - msgid "Today is {month} {day}." - msgstr "Hoy es {day} de {month}." - -The resulting output is correct in each language:: - - English output: "Today is November 26." - Spanish output: "Hoy es 26 de Noviembre." - - -Only translate literal strings -============================== - -As programmers, we're used to using functions in flexible ways. But the -translation functions like ``_()`` and ``gettext()`` can't be used like other -functions. At runtime, they are real functions like any other, but they also -serve as markers for the string extraction process. - -For string extraction to work properly, the translation functions must be -called with only literal strings. If you use them with a computed value, -the string extracter won't have a string to extract. - -The difference between the right way and the wrong way can be very subtle: - -:: - - # BAD: This tries to translate the result of .format() - _("Welcome, {name}".format(name=student_name)) - - # GOOD: Translate the literal string, then use it with .format() - _("Welcome, {name}").format(name=student_name)) - -:: - - # BAD: The dedent always makes the same string, but the extractor can't find it. - _(dedent(""" - .. very long message .. - """)) - - # GOOD: Dedent the translated string. - dedent(_(""" - .. very long message .. - """)) - -:: - - # BAD: The string is separated from _(), the extractor won't find it. - if hello: - msg = "Welcome!" - else: - msg = "Goodbye." - message = _(msg) - - # GOOD: Each string is wrapped in _() - if hello: - message = _("Welcome!") - else: - message = _("Goodbye.") - - -Be aware of nested syntax -========================= - -When translating strings in templated files, you have to be careful of nested -syntax. For example, consider this JavaScript fragment in a Mako template:: - - - -When rendered for a French speaker, it will produce this:: - - - -which is now invalid JavaScript. This can be avoided by using double-quotes -for the JavaScript string. The better solution is to use a filtering function -that properly escapes the string for JavaScript use:: - - <%! - from django.utils.translation import ugettext as _ - from django.utils.html import escapejs - %> - ... - - -which produces:: - - - -Other places that might be problematic are HTML attributes:: - - ${_("I love you.")} - - -Singular vs plural -================== - -It's tempting to improve a message by selecting singular or plural based on a -count:: - - if count == 1: - msg = _("There is 1 file.") - else: - msg = _("There are {file_count} files.").format(file_count=count) - -This is not the correct way to choose a string, because other languages have -different rules for when to use singular and when plural, and there may be more -than two choices! - -One option is not to use different text for different counts:: - - msg = _("Number of files: {file_count}").format(file_count=count) - -If you want to choose based on number, you need to use another gettext variant -to do it:: - - from django.utils.translation import ungettext - msg = ungettext("There is {file_count} file", "There are {file_count} files", count) - msg = msg.format(file_count=count) - -This will properly use count to find a correct string in the translation file, -and then you can use that string to format in the count. - - -Translating too early -===================== - -When the ``_()`` function is called, it will fetch a translated string. It -will use the current user's language to decide which string to fetch. If you -invoke it before we know the user, then it will get the wrong language. - -For example:: - - from django.utils.translation import ugettext as _ - - HELLO = _("Hello") - GOODBYE = _("Goodbye") - - def get_greeting(hello): - if hello: - return HELLO - else: - return GOODBYE - -Here the HELLO and GOODBYE constants are assigned when the module is first -imported, at server startup. There is no current user then, so ugettext will -use the server's default language. When we eventually use those constants to -show a message to the user, they won't be looked up again, and the user will -get the wrong language. - -There are a few ways to deal with this. The first is to avoid calling ``_()`` -until we have the user:: - - def get_greeting(hello): - if hello: - return _("Hello") - else: - return _("Goodbye") - -Another way is to use Django's ugettext_lazy function. Instead of returning -a string, it returns a lazy object that will wait to do the lookup until it is -actually used as a string: - - from django.utils.translation import ugettext_lazy as _ - -This can be tricky because the lazy object doesn't act like a string in all -cases. - -The last way to solve the problem is to mark the string so that it will be -extracted properly, but not actually do the lookup when the constant is -defined:: - - from django.utils.translation import ugettext - - _ = lambda text: text - - HELLO = _("Hello") - GOODBYE = _("Goodbye") - - def get_greeting(hello): - if hello: - return ugettext(HELLO) - else: - return ugettext(GOODBYE) - -Here we define ``_()`` as a pass-through function, so the string will be found -during extraction, but won't be translated too early. Then we use the real -translation function at runtime to get the localized string. - -Multiline Strings -================= - -Translator notes must directly precede the string literals to which they refer. -For example, the translator note here will not be passed along to translators:: - - # Translators: you will not be able to see this note because - # I do not directly prepend the line with the translated string literal. - # See the line directly below this one does not contain part of the string? - long_translated_string = _( - "I am a long string, with many, many words. So many words that it is " - "advisable that I be split over this line." - ) - -In such a case, make sure you format your code so that the string begins on -a line directly below the translator note:: - - # Translators: you will be able to see this note. - # See how the line directly below this one contains the start of the string? - long_translated_string = _("I am a long string, with many, many words. " - "So many words that it is advisable that I " - "be split over this line.") diff --git a/docs/en_us/developers/source/i18n_translators_guide.rst b/docs/en_us/developers/source/i18n_translators_guide.rst deleted file mode 100644 index f87461eb8f..0000000000 --- a/docs/en_us/developers/source/i18n_translators_guide.rst +++ /dev/null @@ -1,361 +0,0 @@ -############################## -Guidelines for Translating edX -############################## - -Open edX uses **Transifex**, an open source translation platform, to power -the translation of edX software into different languages. All translations -are hosted at `Transifex.com `_, which provides -a web application allowing translators to write, submit, and manage their -translations. - -This page explains how to get started with Transifex and provides guidelines -for translators to follow when executing translations. For further discussion, -we welcome you to join the `openedx-translation `_ -mailing list. - -For information on the Transifex process, see the following sections: - -* `Getting Started with Transifex`_ -* `Guidelines for Translators`_ - -See also documentation on -`public translation sandboxes `_. - -Getting Started with Transifex -****************************** - -Contributors wishing to help translate edx-platform and -associated projects can find edX translation projects on -`Transifex `_. -Note: All strings must be both translated **and reviewed** before -we will publish them on the edx.org website. - -You should become a translator only if you feel very confident -in both your language in English. Open edX is written in English, so all -translations will be done from English to your language. - -This guide shows images from the Transifex website in English. Depending -on your browser settings, you may see the site in a different language. The -button locations will be the same. - -This section contains the following subsections: - -* `Signing Up For An Account`_ -* `Joining A Translation Team`_ -* `Joining A Review Team`_ -* `How To Translate With Transifex`_ -* `Requesting A New Language`_ - -Signing Up For An Account -========================= -Go to `https://www.transifex.com/signup/ `_ -and fill out the form to create your free Transifex account, if you don't already -have one. - -Joining A Translation Team -========================== - -1. Once you've set up your account, visit the `edx-platform project `_ - to become a translator for your language. - -2. When you visit the project page, it looks like this. If your language is listed, click - on the name of the language to go to the language's page. Here is an example of choosing - the Japanese translation project: - - .. image:: images/edx-platform-transifex-project.png - -3. Once you're on the language's page, click "Join team" to become part of the translation team - for that language: - - .. image:: images/join-language-team.png - - Once you've joined a translation team, you can begin translating strings immediately! See the - section `Using Transifex`_. - -Joining A Review Team -===================== - -Optionally, you can request to become a `reviewer `_ -for a language. Review teams are incredibly important, because -all strings must be both translated **and reviewed** before -we will publish them on the edx.org website. - -You should join a review team only if you feel very confident in both your language -and in English. To join a review team, request permission from the project coordinator(s). - -1. Click on the "Members" tab of your language: - - .. image:: images/view-team-members.png - - You'll see a list of all the members of your translation team. - -2. Click on one of the Coordinators for the language to be brought to their profile page, - where you can click the "Send message" button to email them and ask for Reviewer access: - - .. image:: images/send-message-button.png - -If the coordinator don't respond, try messaging another coordinator, or message one of the edX project maintainers. -You can find the project maintainers at the top of the main project page: - -.. image:: images/project-maintainers.png - -If you are willing to become a coordinator for your language, let us know in your message. - -How To Translate With Transifex -=============================== - -Once you are a member of a translation or review team, you can click on any of the resources in -the project to begin translating it. For help documentation on Transifex, see the `Transifex translators -help desk `_. -Before you begin, be sure you've reviewed the `Guidelines for Translators`_. - -When visiting a language page, you will see a list of ten distinct resources to translate: - -.. image:: images/project-resources.png - -Focus on translating the non-Studio resources first. That is, please first -translate and review these resources, in this order, before anything else: - - * messages - * mako - * django-partial - * djangojs-partial - * wiki - * notifier-django - * comments-service - -*Only after* the above resources are 100% translated and reviewed, move on to the Studio resources: - - * mako-studio - * djangojs-studio - * django-studio - -Requesting A New Language -========================= - -If your language is **not** listed, click the "Request language" button on the main project page -to start a new translation project for your language: - -.. image:: images/request-new-language.png - -Before requesting a new language, please first make sure your language is not listed! Keep in -mind that variants of your language may exist ("Chinese" versus "Chinese-China") and these -variants may meet your needs. - -An edX translation team member will respond to your request within a few days. If your -language is approved, you will be the coordinator of the project. You can add additional -coordinators, reviewers, and translators as you wish. - -If you request a new language, we ask that you commit to the success of your language's -translation project. Particularly, we expect you to be an active translator and work to -recruit other translators and reviewers so your language project advances to completion, -with all strings translated and reviewed, so that we can publish your work on the edx.org website. - - -Guidelines for Translators -************************** - -Before you dive into translation work, please familiarize yourself with the following -3 guidelines: - -* `Ask for Clarification`_ -* `Working With HTML`_ -* `Working With Placeholders`_ - - -Ask for Clarification -===================== -First and foremost, if you are uncertain of how to translate a string, we strongly -encourage you to reach out to us and ask for clarification! Please join the -`openedx-translation `_ -mailing list and make a post. We can help clarify the string, and even add a note -clarifying the string, which will help translators working on other language projects. - - -Working With HTML -================= - -Translating strings for a website like edX is more complicated than simply translating sentences -from one language to another. Sometimes, sentences (or "strings") will contain -`HTML markup tags `_. It -is very important to understand how to deal with HTML markup. - -Do **not** alter or translate any HTML markup tags. -You should translate the text that is between the tags. HTML markup tags begin and end with ``<`` -and ``>`` characters. - -Spacing is especially important. Adding spaces in an HTML tag (eg changing ```` to ````) -will break the website. - -Examples:: - - String: "If you have a general question about {platform_name} please email - {contact_email}." - - Good translation: "{platform_name}에 대해 일반적인 질문이 있으면 - {contact_email}로 이메일 주십시요." - - Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면 - {contact_email}로 이메일 주십시요." - - Please do not remove the HTML tags. - - Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면 - {contact_email}로 이메일 주십시요." - - Do not translate the HTML tags. Please use the given HTML tags. - - Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면 - {contact_email}로 이메일 주십시요." - - Do not change the HTML tags to something new. Please use the given HTML tags. - - Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면 - < a href = " mailto : {contact_email} " > {contact_email} < / a >로 이메일 주십시요." - - Do not add additional spacing to the HTML tags. Please use the given HTML tags. - - -Working With Placeholders -========================= - -Strings in programs sometimes need to have data inserted into them -before being displayed to the user. Data placeholders label the places in the string where the -data will go. Strings can also have markup like HTML included. It's very important to preserve -the placeholders and markup so that the web site will work properly. - -Placeholders come in a few different forms. Often, they are named so that data will be placed into -the proper placeholder. Please familiarize yourself with all the different forms to make your -translation successful. - -Summary Of Placeholders ------------------------ - -+-------------------------+ -| Placeholder Forms | -+=========================+ -| ``{student_name}`` | -+-------------------------+ -| ``%(student_name)s`` | -+-------------------------+ -| ``<%= student_name %>`` | -+-------------------------+ - -When dealing with placeholders, you must follow these rules: - -* **Do not** translate the placeholder (for example, changing ``{day}`` to ``{día}``). -* **Do not** alter or remove the punctuation of the placeholder string (for example, changing a ``_`` to a ``-``). -* **Do not** alter the capitalization of the placeholder string (for example, changing ``{day}`` to ``{Day}``). -* **Do not** alter the spacing of the placeholder string (for example, changing ``{day}`` to ``{ day }``). - -Please continue reading for examples of each type of placeholder form inside a string. - -1. Do **not** alter or translate placeholder strings in between curly braces (``{ }``). Strings - inside curly braces will be replaced with different strings while the code - is executing. Changing the content of the curly braces will cause code to break. - - The placeholder string inside of the braces will give you clues as to what type of data will - be presented in the final string. For example, ``{student_name}`` will be replaced with the name - of a student, whereas ``{contact_email}`` will be replaced with an email address that users can - use to contact us. This will give you some context when you are translating sentences with - placeholders. - - Altering the strings includes: changing, removing, or adding punctuation, changing - the capitalization, or adding or removing given spacing. So if the placeholder string - looks like ``{placeholder_string}``, you should not change it at all, eg ``{Placeholder_String}``, - ``{placeholder-string}``, ``{ placeholder_string }``, ``{placeholder string}``. All of - these changes have the potential to break the software. - - Examples:: - - String: "Welcome back {student_name}!" - - Good translation: "¡Bienvenido {student_name}!" - - Bad translation: "¡Bienvenido {nombre de estudiente}!" - Do not translate placeholder string - You must use {student_name} exactly as-is. - - Bad translation: "¡Bienvenido {student-name}!" - Do not alter the placeholder string punctuation - you must use {student_name} exactly as-is. - - Bad translation: "¡Bienvenido {Student_Name}!" - Do not alter the placeholder string capitalization - you must use {student_name} exactly as-is. - - Bad translation: "¡Bienvenido { student_name }!" - Do not add additional spacing inside the {} - you must use {student_name} exactly as-is. - - You may rearrange the order of these strings, depending on the requirements of your language. - For example, in English the name of the month precedes the day (January 23), wheras in Spanish, - the day precedes the month (23 de enero). - - Example:: - - String: "Today is {month} {day}." - - Good translation: "Hoy es {day} de {month}." - - -2. Do **not** alter or translate placeholder strings that begin with a ``%``, then have a string - inside parenthesis, and then conclude with an 's' or 'd'. You must preserve the whole form. - - As in the previous example, you must not add, change, or remove punctuation, change capitalization, - or add in new spacing. - - Examples:: - - String: "Welcome back %(student_name)s!" - - Good translation: "¡Bienvenido %(student_name)s!" - - Bad translation: "¡Bienvenido %(nombre de estudiente)s!" - Do not translate placeholder strings - You must use %(student_name)s exactly as-is. - - Bad translation: "¡Bienvenido %(student-name)s!" - Do not alter the placeholder string punctuation - you must use %(student_name)s exactly as-is. - - Bad translation: "¡Bienvenido %(Student_Name)s!" - Do not alter the placeholder string capitalization - you must use %(student_name)s exactly as-is. - - Bad translation: "¡Bienvenido %( student_name )s!" - Do not add additional spacing inside the () - you must use %(student_name)s exactly as-is. - - Bad translation: "¡Bienvenido (student_name)!" - Do not remove the '%' or 's' - you must use %(student_name)s exactly as-is. - - You may rearrange the order of these strings, depending on the requirements of your language. - For example, in English the name of the month precedes the day (January 23), wheras in Spanish, - the day precedes the month (23 de enero). - - Example:: - - String: "Today is %(month)s %(day)d." - - Good translation: "Hoy es %(day)d de %(month)s." - - -3. Do **not** alter or translate placeholder strings that appear within a ``<%= %>`` block. Placeholder - strings in this format look like this: ``<%= student_name %>``. - - As in the previous examples, you must not add, change, or remove punctuation, change capitalization, - or add in new spacing. - - Examples:: - - String: "Welcome back <%= student_name %>!" - - Good translation: "¡Bienvenido <%= student_name %>!" - - Bad translation: "¡Bienvenido <%= nombre de estudiente %>!" - Do not translate placeholder strings - You must use <%= student_name %> exactly as-is. - - Bad translation: "¡Bienvenido <%= student-name %>!" - Do not alter the placeholder string punctuation - you must use <%= student_name %> exactly as-is. - - Bad translation: "¡Bienvenido <%= Student_Name %>!" - Do not alter the placeholder string capitalization - you must use <%= student_name %> exactly as-is. - - Bad translation: "¡Bienvenido < % = student_name % >!" - Do not add additional spacing inside the <%= %> - you must use <%= student_name %> exactly as-is. - - Bad translation: "¡Bienvenido !" - Do not remove or change the '<%=' or '%>' - you must use <%= student_name %> exactly as-is diff --git a/docs/en_us/developers/source/images/JavaScriptInputExample.png b/docs/en_us/developers/source/images/JavaScriptInputExample.png deleted file mode 100644 index 1c9220de00..0000000000 Binary files a/docs/en_us/developers/source/images/JavaScriptInputExample.png and /dev/null differ diff --git a/docs/en_us/developers/source/images/edx-platform-transifex-project.png b/docs/en_us/developers/source/images/edx-platform-transifex-project.png deleted file mode 100644 index ef720babba..0000000000 Binary files a/docs/en_us/developers/source/images/edx-platform-transifex-project.png and /dev/null differ diff --git a/docs/en_us/developers/source/images/join-language-team.png b/docs/en_us/developers/source/images/join-language-team.png deleted file mode 100644 index 346b0f32ff..0000000000 Binary files a/docs/en_us/developers/source/images/join-language-team.png and /dev/null differ diff --git a/docs/en_us/developers/source/images/project-maintainers.png b/docs/en_us/developers/source/images/project-maintainers.png deleted file mode 100644 index ab424d499c..0000000000 Binary files a/docs/en_us/developers/source/images/project-maintainers.png and /dev/null differ diff --git a/docs/en_us/developers/source/images/project-resources.png b/docs/en_us/developers/source/images/project-resources.png deleted file mode 100644 index 9c739aafe0..0000000000 Binary files a/docs/en_us/developers/source/images/project-resources.png and /dev/null differ diff --git a/docs/en_us/developers/source/images/request-new-language.png b/docs/en_us/developers/source/images/request-new-language.png deleted file mode 100644 index f612e2fe52..0000000000 Binary files a/docs/en_us/developers/source/images/request-new-language.png and /dev/null differ diff --git a/docs/en_us/developers/source/images/send-message-button.png b/docs/en_us/developers/source/images/send-message-button.png deleted file mode 100644 index 8f2aee986f..0000000000 Binary files a/docs/en_us/developers/source/images/send-message-button.png and /dev/null differ diff --git a/docs/en_us/developers/source/images/view-team-members.png b/docs/en_us/developers/source/images/view-team-members.png deleted file mode 100644 index c1896655dc..0000000000 Binary files a/docs/en_us/developers/source/images/view-team-members.png and /dev/null differ diff --git a/docs/en_us/developers/source/index.rst b/docs/en_us/developers/source/index.rst deleted file mode 100644 index 2ecae648c3..0000000000 --- a/docs/en_us/developers/source/index.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. 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. - -edX Developer's Guide -=================================== - -Contents: - -.. this is wildly disorganized, and is basically just a dumping ground for - .rst files at the moment. - -.. toctree:: - :maxdepth: 2 - - change_log - preface.rst - browsers.rst - overview.rst - extending_platform/index - modulestores/index - xblocks.rst - pavelib.rst - public_sandboxes.rst - analytics.rst - process/index - testing/index - code-considerations - deploy-new-service - -APIs ------ - -.. toctree:: - :maxdepth: 2 - - djangoapps.rst - common-lib.rst - experiments.rst - -Internationalization ---------------------- - -.. toctree:: - :maxdepth: 2 - - i18n.rst - i18n_translators_guide.rst - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/en_us/developers/source/lms.rst b/docs/en_us/developers/source/lms.rst deleted file mode 100644 index c7ba7dde62..0000000000 --- a/docs/en_us/developers/source/lms.rst +++ /dev/null @@ -1,314 +0,0 @@ -******************************************* -LMS module -******************************************* - -.. module:: lms - -Branding -======== - -.. 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: - -Circuit -======= - -.. automodule:: circuit - :members: - :show-inheritance: - -Models ------- - -.. automodule:: circuit.models - :members: - :show-inheritance: - -Views ------ - -.. automodule:: circuit.views - :members: - :show-inheritance: - - -Course_wiki -=========== - -.. automodule:: course_wiki - :members: - :show-inheritance: - -Course Nav ----------- - -.. .. automodule:: course_wiki.course_nav -.. :members: -.. :show-inheritance: - -Views ------ - -.. automodule:: course_wiki.views - :members: - :show-inheritance: - -Editors -------- - -.. automodule:: course_wiki.editors - :members: - :show-inheritance: - -Courseware -========== - -.. automodule:: courseware - :members: - :show-inheritance: - -Access ------- - -.. automodule:: courseware.access - :members: - :show-inheritance: - -Admin ------ - -.. automodule:: courseware.admin - :members: - :show-inheritance: - -Courses -------- - -.. automodule:: courseware.courses - :members: - :show-inheritance: - -Grades ------- - -.. automodule:: courseware.grades - :members: - :show-inheritance: - -Models ------- - -.. automodule:: courseware.models - :members: - :show-inheritance: - -Progress --------- - -.. automodule:: courseware.progress - :members: - :show-inheritance: - -Tabs ----- - -.. automodule:: courseware.tabs - :members: - :show-inheritance: - - -Dashboard -========= - -.. automodule:: dashboard - :members: - :show-inheritance: - -Models ------- - -.. automodule:: dashboard.models - :members: - :show-inheritance: - -Views ------ - -.. automodule:: dashboard.views - :members: - :show-inheritance: - - -Django comment client -===================== - -.. automodule:: django_comment_client - :members: - :show-inheritance: - -Models ------- - -.. automodule:: django_comment_client.models - :members: - :show-inheritance: - - -Heartbeat -========= - -.. automodule:: heartbeat - :members: - :show-inheritance: - -Instructor -========== - -.. automodule:: instructor - :members: - :show-inheritance: - -Views ------ - -.. automodule:: instructor.views - :members: - :show-inheritance: - - -Lisenses -======== - -.. automodule:: licenses - :members: - :show-inheritance: - -Models ------- - -.. automodule:: licenses.models - :members: - :show-inheritance: - -Views ------ - -.. automodule:: licenses.views - :members: - :show-inheritance: - - -LMS migration -============= - -.. automodule:: lms_migration - :members: - :show-inheritance: - -Migration ---------- - -.. automodule:: lms_migration.migrate - :members: - :show-inheritance: - -Multicourse -=========== - -.. automodule:: multicourse - :members: - :show-inheritance: - -Psychometrics -============= - -.. automodule:: psychometrics - :members: - :show-inheritance: - -Models ------- - -.. automodule:: psychometrics.models - :members: - :show-inheritance: - -Admin ------ - -.. automodule:: psychometrics.admin - :members: - :show-inheritance: - -Psychoanalyze -------------- - -.. automodule:: psychometrics.psychoanalyze - :members: - :show-inheritance: - - -Static template view -==================== - -.. automodule:: static_template_view - :members: - :show-inheritance: - -Views ------ - -.. automodule:: static_template_view.views - :members: - :show-inheritance: - - -Static book -=========== - -.. automodule:: staticbook - :members: - :show-inheritance: - -Models ------- - -.. automodule:: staticbook.models - :members: - :show-inheritance: - -Views ------ - -.. automodule:: staticbook.views - :members: - :show-inheritance: diff --git a/docs/en_us/developers/source/modulestore.rst b/docs/en_us/developers/source/modulestore.rst deleted file mode 100644 index a9ac4b9190..0000000000 --- a/docs/en_us/developers/source/modulestore.rst +++ /dev/null @@ -1,84 +0,0 @@ -******************************************* -Xmodule.Modulestore -******************************************* - -.. contents:: Table of Contents - -.. automodule:: xmodule.modulestore - :members: - :show-inheritance: - -Modulestores -============ - -These implement the :class:`.ModuleStoreRead` and :class:`.ModuleStoreWrite` -to provide access to XBlock content. - -.. automodule:: xmodule.modulestore.xml - :members: - :show-inheritance: - -.. automodule:: xmodule.modulestore.mongo - :members: - :show-inheritance: - -.. automodule:: xmodule.modulestore.split_mongo - :members: - :show-inheritance: - - -Modulestore Helpers -------------------- - -These packages provide utilities for easier use of modulestores, -and migrating data between modulestores. - -.. automodule:: xmodule.modulestore.search - :members: - :show-inheritance: - -.. automodule:: xmodule.modulestore.mongoengine_fields - :members: - :show-inheritance: - -.. automodule:: xmodule.modulestore.split_migrator - :members: - :show-inheritance: - -.. automodule:: xmodule.modulestore.store_utilities - :members: - :show-inheritance: - - -Xml Import/Export -================= - -These packages focus on importing and exporting xml serialized -course content to/from modulestores. - -.. automodule:: xmodule.modulestore.xml_exporter - :members: - :show-inheritance: - -.. automodule:: xmodule.modulestore.xml_importer - :members: - :show-inheritance: - - - -Miscellaneous -============= - -.. automodule:: xmodule.modulestore.django - :members: - :show-inheritance: - -.. automodule:: xmodule.modulestore.exceptions - :members: - :show-inheritance: - -.. automodule:: xmodule.modulestore.inheritance - :members: - :show-inheritance: - - diff --git a/docs/en_us/developers/source/modulestores/index.rst b/docs/en_us/developers/source/modulestores/index.rst deleted file mode 100644 index a16c92d84b..0000000000 --- a/docs/en_us/developers/source/modulestores/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _edX Modulestores: - -########################### -edX Modulestores -########################### - -.. toctree:: - :maxdepth: 2 - - overview - mixedmodulestore - split-mongo \ No newline at end of file diff --git a/docs/en_us/developers/source/modulestores/mixedmodulestore.rst b/docs/en_us/developers/source/modulestores/mixedmodulestore.rst deleted file mode 100644 index 3a8d84c9f8..0000000000 --- a/docs/en_us/developers/source/modulestores/mixedmodulestore.rst +++ /dev/null @@ -1,12 +0,0 @@ -################# -MixedModuleStore -################# - -MixedModuleStore provides a common API for all modulestore functions. - -In addition, MixedModuleStore allows you to select which modulestore a -specific course is stored in (XMLModuleStore, DraftModuleStore, Split Mongo) -and routes requests for that course to the correct modulestore. - -MixedModuleStore can also handle some conversions from one modulestore to -another. \ No newline at end of file diff --git a/docs/en_us/developers/source/modulestores/overview.rst b/docs/en_us/developers/source/modulestores/overview.rst deleted file mode 100644 index 5ffa719d62..0000000000 --- a/docs/en_us/developers/source/modulestores/overview.rst +++ /dev/null @@ -1,43 +0,0 @@ -################################# -Overview of the edX Modulestores -################################# - -The edX Platform uses several different modulestores to store course data. Each -of these modulestores is in use on edx.org. - -See: - -* `XMLModuleStore`_ -* `DraftModuleStore`_ -* :ref:`Split Mongo Modulestore` - -*************** -XMLModuleStore -*************** - -The XMLModuleStore was the first modulestore used for the edX Platform. - -XMLModuleStore uses a file system that stores XML-based courses. When the LMS -server starts, XMLModuleStore loads every block for every course into memory. - -XMLModuleStore is read-only and does not enable users to change a course -without restarting the server. - -***************** -DraftModuleStore -***************** - -DraftModuleStore was the next generation modulestore and provides greater -scalability by allowing random access to course blocks and loading blocks on -requests. - -DraftModuleStore allows editing of courses without restarting the server. - -In addition, DraftModuleStore stores a draft version of some types of blocks. - -***************** -Split Mongo -***************** - -Split Mongo is the newest modulestore. See the :ref:`Split Mongo Modulestore` -chapter for more information. \ No newline at end of file diff --git a/docs/en_us/developers/source/modulestores/split-mongo.rst b/docs/en_us/developers/source/modulestores/split-mongo.rst deleted file mode 100644 index c46e2fdfaf..0000000000 --- a/docs/en_us/developers/source/modulestores/split-mongo.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. _Split Mongo Modulestore: - -############################ -Split Mongo Modulestore -############################ - -See: - -* `Overview`_ -* `Split Mongo Data Model`_ -* `Split Mongo Capabilities`_ - - -************************ -Overview -************************ - -*Split Mongo* is the term used for the new edX modulestore. Split Mongo is -built on mongoDB. For information about mongoDB, see the `mongoDB website`_. - -The "split" in Split Mongo refers to how a course is split into three types of -information: - -* The course identity, referred to as the course index -* The course structure -* The course content, referred to as XBlock definitions. - -This separation of identity, structure, and content enables course authors to -use more advanced capabilities when developing and managing courses. - -.. _mongoDB website: http://www.mongodb.org - -************************ -Split Mongo Data Model -************************ - -In the Split Mongo data model, edX courses are split into three collections: - -* `Course Index`_ -* `Course Structures`_ -* `XBlock Definitions`_ - -============= -Course Index -============= - -The course index is a dictionary that stores course IDs. Each course ID points -to a course structure. - -The course index supports multiple branches of a course. The index can store -multiple entries for a course ID, with each entry pointing to a different -course structure that corresponds to a different branch. - -As currently implemented, for each course, there is a branch for both the -published and draft versions of the course. The published and draft branches of -the course point to different structures. - -In the edX Platform: - -* Students using the LMS see and interact with the published version of the - course. - -* Course staff using edX Studio make changes to the draft version of the - course. - - * When the user changes a the course outline, display names, the course - about page, course updates, other course pages, sections or subsections, - the draft branch is automatically published; that is, it becomes the - published branch. - - * For units and components, changes are saved in the draft branch. The user - must publish the unit to change the draft branch to the published branch. - When the user begins another set of changes, the draft branch is updated. - -Course Reruns -************** - -The edX Platform enables you to rerun a course. When you rerun a course, a new -course index is created. The new course index points to the same course -structure as the original course index. - -========================== -Course Structures -========================== - -The course structure defines, or outlines, the content of a course. - -A course structure is made up of blocks in a tree data structure. Blocks are -objects in a course, such as the course itself, sections, subsections, and -units. A block can reference other blocks; for example, a section references -one or more subsections. Each block has a unique ID that is generated by the -edX Platform. - -Each block in the course structure points to an XBlock definition. Different -blocks, in the same or in different structures, can point to the same -definition. - -Course structures, and each block within a structure, are versioned. That is, -when a course author changes a course, or a block in the course, a new course -structure is saved; the previous course structure, and previous versions of -blocks within the structure, remain in the database and are not modified. - -========================== -XBlock Definitions -========================== - -XBlock definitions contain the content of each block. For some blocks, such as -sections and subsections, the definition consists of the block's display name. -For components, such as HTML or problem components, the definition also -contains the content of the object. A definition can be referenced by multiple -blocks. - -XBlock definitions are versioned. That is, when a course author changes -content, a new XBlock definition for that object is saved; the previous -definition remains in the database and is not modified. - -************************ -Split Mongo Capabilities -************************ - -The Split Mongo data model enables the edX Platform to implement advanced -content management functionality. Specifically, Split Mongo is designed to -enable: - -* `Multiple Course Branches`_ -* `Versioning`_ -* `Content Reuse`_ - -While these capabilities are not fully implemented in the edX Platform, Split -Mongo is designed to allow future enhancements that enable these content -management capabilities. - -======================== -Multiple Course Branches -======================== - -Split Mongo enables multiple branches of a course. The `course index _ can have multiple entries for a course ID, each of which points to a -different structure. - -The edX Platform currently uses a draft and a published branch for a course. -Future enhancements may use other branches. - -============ -Versioning -============ - -In Split Mongo, every change to a course or a block within the course is saved, -with the time and user recorded. - -Versioning enables future enhancements such as allowing course authors to -revert a course or block to a previous version. - -============== -Content Reuse -============== - -By using pointers to reference XBlock definitions from `course structures -`_, Split Mongo enables content reuse. A single `XBlock -definition `_ can be referenced from multiple course -structures. - -Future enhancements to the edX Platform can allow course authors to reuse an -XBlock in multiple contexts, streamlining course development and maintenance. \ No newline at end of file diff --git a/docs/en_us/developers/source/opaque-keys.rst b/docs/en_us/developers/source/opaque-keys.rst deleted file mode 100644 index f845144254..0000000000 --- a/docs/en_us/developers/source/opaque-keys.rst +++ /dev/null @@ -1,11 +0,0 @@ -******************************************* -OpaqueKeys -******************************************* -.. module:: opaque_keys - -OpaqueKeys -========== - -.. automodule:: opaque_keys - :members: - :show-inheritance: \ No newline at end of file diff --git a/docs/en_us/developers/source/overview.rst b/docs/en_us/developers/source/overview.rst deleted file mode 100644 index a6d71cbd88..0000000000 --- a/docs/en_us/developers/source/overview.rst +++ /dev/null @@ -1,9 +0,0 @@ -******************************************* -Overview -******************************************* - - -This is EdX Dev documentation, mainly extracted from docstrings. -Autogenerated by Sphinx from python code. -Soon support for JS will be impemented. - diff --git a/docs/en_us/developers/source/pavelib.rst b/docs/en_us/developers/source/pavelib.rst deleted file mode 100644 index 3bb3467e7f..0000000000 --- a/docs/en_us/developers/source/pavelib.rst +++ /dev/null @@ -1,165 +0,0 @@ -******************************************* -Paver -******************************************* - - -Paver provides a standardised way of managing development and operational tasks in edX. - -To run individual commands, use the following syntax: - -paver --option=