docs: add new links.rst for XBlock Tutorial docs

openedx · Nov 2, 2023 · 7897f57 · 7897f57
1 parent 7689c48
commit 7897f57
Show file tree

Hide file tree

Showing 30 changed files with 84 additions and 73 deletions.
diff --git a/docs/links.rst b/docs/links.rst
@@ -0,0 +1,7 @@
+.. Include this file in any file that includes a non-doc link.
+
+.. _thumbs.py: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/thumbs/thumbs.py
+
+.. _thumbs.js: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/thumbs/static/js/src/thumbs.js
+
+.. _Thumbs XBlock:  https://github.com/openedx/xblock-sdk/tree/master/sample_xblocks/thumbs
diff --git a/docs/xblock-tutorial/anatomy/html.rst b/docs/xblock-tutorial/anatomy/html.rst
@@ -1,8 +1,8 @@
 .. _The XBlock HTML File:
 
-#######################
+####################
 The XBlock HTML File
-#######################
+####################
 
 This section of the tutorial walks through the HTML file, `thumbs.html`_,  that
 is part of the Thumbs XBlock in the XBlock SDK.
@@ -26,4 +26,4 @@ Note the following details about the HTML file.
 * The values ``self.upvotes`` and ``self.downvotes`` reference the fields in
   the XBlock Python class.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/anatomy/index.rst b/docs/xblock-tutorial/anatomy/index.rst
@@ -1,8 +1,8 @@
 .. _Anatomy of an XBlock:
 
-#####################
+####################
 Anatomy of an XBlock
-#####################
+####################
 
 This part of the tutorial explains the XBlock skeleton, and uses examples from
 the `Thumbs XBlock`_ that is installed with the XBlock SDK.
@@ -11,7 +11,7 @@ The Thumbs XBlock enables learners to vote up or down. The Thumbs XBlock keeps
 track of vote totals.
 
 For information about making the XBlock that you created function like the
-example Thumbs XBlocK, see :ref:`Customize Your XBlock`.
+example Thumbs XBlock, see :ref:`Customize Your XBlock`.
 
 .. toctree::
    :maxdepth: 2
@@ -21,4 +21,4 @@ example Thumbs XBlocK, see :ref:`Customize Your XBlock`.
    javascript
    stylesheets
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/anatomy/javascript.rst b/docs/xblock-tutorial/anatomy/javascript.rst
@@ -1,8 +1,8 @@
 .. _The XBlock JavaScript File:
 
-###########################
+##########################
 The XBlock JavaScript File
-###########################
+##########################
 
 This section of the tutorial walks through the JavaScript file, `thumbs.js`_,
 that is part of the Thumbs XBlock in the XBlock SDK.
@@ -45,4 +45,4 @@ Note the following details about the JavaScript file.
 The XBlock JavaScript code can also use the ``children`` and ``childMap``
 functions as needed. For more information, see :ref:`XBlock Children`.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/anatomy/python.rst b/docs/xblock-tutorial/anatomy/python.rst
@@ -93,4 +93,4 @@ Note the following details about the vote handler.
 
 For more information, see :ref:`Handler Methods`.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/anatomy/stylesheets.rst b/docs/xblock-tutorial/anatomy/stylesheets.rst
@@ -1,8 +1,8 @@
 .. _The XBlock Stylesheets:
 
-#######################
+######################
 The XBlock Stylesheets
-#######################
+######################
 
 This section of the tutorial walks through the CSS file, `thumbs.css`_,  that
 is part of the Thumbs XBlock in the XBlock SDK.
@@ -19,4 +19,4 @@ application.
 The styles in ``thumbs.css`` are referenced in the :ref:`XBlock HTML file <The
 XBlock HTML File>`.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/concepts/children.rst b/docs/xblock-tutorial/concepts/children.rst
@@ -71,4 +71,4 @@ following methods.
 
 .. examples?
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/concepts/events.rst b/docs/xblock-tutorial/concepts/events.rst
@@ -103,4 +103,4 @@ have a ``has_score`` variable set to ``True``.
 
     has_score = True
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/concepts/fields.rst b/docs/xblock-tutorial/concepts/fields.rst
@@ -1,8 +1,8 @@
 .. _XBlock Fields:
 
-####################
+#############
 XBlock Fields
-####################
+#############
 
 You use XBlock fields to store state data for your XBlock.
 
@@ -256,20 +256,20 @@ You can customize the OLX representation of the XBlock by using the
 
 .. add links to api doc
 
-*********************************************
+**************************************
 Field Requirements in the edX Platform
-*********************************************
+**************************************
 
 For information about field requirements in the edX Platform, see :ref:`edX LMS
 <EdX Learning Management System as an XBlock Runtime>` and
 :ref:`edX Studio <EdX Studio as an XBlock Runtime>`.
 
-*********************************************
+******************************
 Default Fields in a New XBlock
-*********************************************
+******************************
 
 When you create a new XBlock, the ``count`` field is added to the Python file
 by default. This field is for demonstration purposes and you should replace it
 with your own field definitions.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/concepts/fragments.rst b/docs/xblock-tutorial/concepts/fragments.rst
@@ -1,8 +1,8 @@
 .. _XBlock Fragments:
 
-####################
+################
 XBlock Fragments
-####################
+################
 
 A fragment is a part of a web page returned by an XBlock view method. 
 
@@ -101,4 +101,4 @@ CSS strings generated from the XBlock's static files.
 
   TBP
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/concepts/index.rst b/docs/xblock-tutorial/concepts/index.rst
@@ -1,8 +1,8 @@
 .. _XBlock Concepts:
 
-####################
+###############
 XBlock Concepts
-####################
+###############
 
 You build XBlocks that course teams use to create independent course components
 that work seamlessly with other components in an online course. For example,

diff --git a/docs/xblock-tutorial/concepts/methods.rst b/docs/xblock-tutorial/concepts/methods.rst
@@ -1,8 +1,8 @@
 .. _XBlock Methods:
 
-####################
+##############
 XBlock Methods
-####################
+##############
 
 You use XBlock methods in the XBlock Python file to define the behavior of your
 XBlock.
@@ -13,9 +13,9 @@ XBlock.
 
 .. _View Methods:
 
-***************
+************
 View Methods
-***************
+************
 
 XBlock view methods are Python methods invoked by the XBlock runtime to render
 the XBlock.
@@ -97,9 +97,9 @@ handler for voting.
 
         return {'up': self.upvotes, 'down': self.downvotes}
 
-*********************************************
+*******************************
 Default Methods in a New XBlock
-*********************************************
+*******************************
 
 When you create a new XBlock, two methods are added automatically.
 
@@ -113,4 +113,4 @@ When you create a new XBlock, two methods are added automatically.
   This method is for demonstration purposes and you can remove it.
 
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/concepts/runtimes.rst b/docs/xblock-tutorial/concepts/runtimes.rst
@@ -1,8 +1,8 @@
 .. _XBlock Runtimes:
 
-####################
+###############
 XBlock Runtimes
-####################
+###############
 
 An XBlock runtime is the application that hosts XBlock. For example, the XBlock
 SDK, the :ref:`edX LMS <EdX Learning Management System as an XBlock Runtime>`,
@@ -14,9 +14,9 @@ URL.
  :local:
  :depth: 1
 
-******************
+*****************
 Runtime Functions
-******************
+*****************
 
 An XBlock runtime application performs the following functions.
 
@@ -32,9 +32,9 @@ An XBlock runtime application performs the following functions.
 * Route handler requests from the client-side XBlock to the server-side
   handlers.
 
-******************
+*****************
 Extending XBlocks
-******************
+*****************
 
 A runtime application can have mixin classes that it combines with your XBlock
 class. Therefore, your instances of your XBlock might be subclasses of your
@@ -44,9 +44,9 @@ By using mixins, a runtime application can add field data and methods to all
 XBlocks that it hosts, without requiring that XBlocks themselves are aware of
 the runtime they are being hosted in.
 
-********************
+*******************
 JavaScript Runtimes
-********************
+*******************
 
 The application that runs XBlocks uses a JavaScript runtime to load XBlocks.
 Specifically, the JavaScript runtime provides the following functions to
@@ -58,9 +58,9 @@ XBlocks.
 
 * A map of the XBlock children
 
-==================================
+=================================
 The XBlock SDK JavaScript Runtime
-==================================
+=================================
 
 The file `1.js`_ in the XBlock SDK provides the JavaScript runtime for the
 workbench.
@@ -109,9 +109,9 @@ the handler from the XBlock runtime.
 
     var handlerUrl = runtime.handlerUrl(element, 'vote');
 
-================
+===============
 XBlock Children
-================
+===============
 
 The JavaScript runtime also returns the list of child XBlocks to the XBlock.
 
@@ -130,9 +130,9 @@ children to the XBlock.
 An XBlock uses the ``children`` method when it needs to iterate over an ordered
 list of its child XBlocks.
 
-=================
+================
 XBlock Child Map
-=================
+================
 
 The JavaScript runtime also returns the a map of child XBlocks to the running
 XBlock.
@@ -182,4 +182,4 @@ For more information, see `XBlock Runtime API`_ in the *XBlock API Guide*.
 
 
 .. _XBlock Runtime API: http://edx.readthedocs.io/projects/xblock/en/latest/
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/customize/custom-html.rst b/docs/xblock-tutorial/customize/custom-html.rst
@@ -73,4 +73,4 @@ Next Step
 After you complete your customizations to the HTML file, you continue on and
 :ref:`customize the XBlock JavaScript file<Customize myxblock.js>`.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/customize/custom-javascript.rst b/docs/xblock-tutorial/customize/custom-javascript.rst
@@ -76,4 +76,4 @@ Next Step
 After you complete your customizations to the JavaScript file, you continue on
 and :ref:`customize the XBlock CSS file<Customize myxblock.css>`.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/customize/custom-python.rst b/docs/xblock-tutorial/customize/custom-python.rst
@@ -169,4 +169,4 @@ Next Step
 After you complete your customizations to the Python file, you continue on and
 :ref:`customize the XBlock HTML file<Customize myxblock.html>`.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/customize/custom-stylesheets.rst b/docs/xblock-tutorial/customize/custom-stylesheets.rst
@@ -63,4 +63,4 @@ matches the code in the Thumbs XBlock.
 The styles in ``thumbs.css`` are referenced in the :ref:`XBlock HTML file <The
 XBlock HTML File>`.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/customize/index.rst b/docs/xblock-tutorial/customize/index.rst
@@ -22,4 +22,4 @@ For more information about the different components of an XBlock, see
    custom-javascript
    custom-stylesheets
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/edx_platform/devstack.rst b/docs/xblock-tutorial/edx_platform/devstack.rst
@@ -121,4 +121,4 @@ For more information about working with components in Studio, see
 :ref:`opencoursestaff:Developing Course Components` in the *Building and
 Running an Open edX* guide.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/edx_platform/edx.rst b/docs/xblock-tutorial/edx_platform/edx.rst
@@ -36,4 +36,4 @@ it is appropriate for use on edx.org. Specifically, edX will review your XBlock
 for security, scalability, accessibility, and fitness of purpose. You should be
 prepared to respond to questions and comments from edX in your pull request.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/edx_platform/edx_lms.rst b/docs/xblock-tutorial/edx_platform/edx_lms.rst
@@ -173,4 +173,4 @@ in order to observe the translated strings for your chosen locale.
     matched by the LMS, and even if matches are found, the translations may be
     incorrect in the context of your specific XBlock.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/edx_platform/edx_studio.rst b/docs/xblock-tutorial/edx_platform/edx_studio.rst
@@ -39,4 +39,4 @@ Studio requires XBlocks to have the following properties.
   Studio editor.
 
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/edx_platform/index.rst b/docs/xblock-tutorial/edx_platform/index.rst
@@ -1,8 +1,8 @@
 .. _XBlocks and the edX Platform:
 
-#############################
+############################
 XBlocks and the edX Platform
-#############################
+############################
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/xblock-tutorial/front_matter/read_me.rst b/docs/xblock-tutorial/front_matter/read_me.rst
@@ -8,9 +8,13 @@ GitHub.
 
 https://github.com/openedx/edx-documentation/tree/master/en_us/xblock-tutorial/source
 
-The edX documentation team welcomes contributions from Open edX community
-members. You can find guidelines for how to `contribute to edX Documentation`_
-in the GitHub edx/edx-documentation repository.
 
-.. include:: ../../../links/links.rst
+The Open edX community welcomes contributions from other Open edX community
+members. You can find guidelines for how to `contribute to Open edX documentation`_
+in the GitHub openedx/docs.openedx.org repository - although note that these
+specific docs are authored in the openedx/XBlock repository.
+
+.. _contribute to Open edX documentation: https://github.com/openedx/docs.openedx.org#readme
+
+.. include:: ../../links.rst
 
diff --git a/docs/xblock-tutorial/getting_started/create_first_xblock.rst b/docs/xblock-tutorial/getting_started/create_first_xblock.rst
@@ -30,4 +30,4 @@ XBlock Software Development Kit>`, about the :ref:`anatomy of an XBlock
 <Anatomy of an XBlock>`, and :ref:`how to customize your new XBlock <Customize
 Your XBlock>`.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/getting_started/prereqs.rst b/docs/xblock-tutorial/getting_started/prereqs.rst
@@ -54,4 +54,4 @@ instructions.
 For information on creating the virtual environment for your XBlock, see
 :ref:`Create and Activate the Virtual Environment`.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/getting_started/setup_sdk.rst b/docs/xblock-tutorial/getting_started/setup_sdk.rst
@@ -70,4 +70,4 @@ Then create the virtual environment in your ``xblock_development`` directory.
 
 When the requirements are installed, you are in the ``xblock_development`` directory, which contains the ``venv`` and ``xblock-sdk`` subdirectories. You can now :ref:`create your first XBlock <Create Your First XBlock>`.
 
-.. include:: ../../../links/links.rst
+.. include:: ../../links.rst
Original file line number	Diff line number	Diff line change
Expand Up		@@ -93,4 +93,4 @@ Note the following details about the vote handler.

		For more information, see :ref:`Handler Methods`.

		.. include:: ../../../links/links.rst
		.. include:: ../../links.rst
Original file line number	Diff line number	Diff line change
Expand Up		@@ -71,4 +71,4 @@ following methods.

		.. examples?

		.. include:: ../../../links/links.rst
		.. include:: ../../links.rst
Original file line number	Diff line number	Diff line change
Expand Up		@@ -103,4 +103,4 @@ have a ``has_score`` variable set to ``True``.

		has_score = True

		.. include:: ../../../links/links.rst
		.. include:: ../../links.rst
Original file line number	Diff line number	Diff line change
Expand Up		@@ -39,4 +39,4 @@ Studio requires XBlocks to have the following properties.
		Studio editor.


		.. include:: ../../../links/links.rst
		.. include:: ../../links.rst
Original file line number	Diff line number	Diff line change
Expand Up		@@ -70,4 +70,4 @@ Then create the virtual environment in your ``xblock_development`` directory.

		When the requirements are installed, you are in the ``xblock_development`` directory, which contains the ``venv`` and ``xblock-sdk`` subdirectories. You can now :ref:`create your first XBlock <Create Your First XBlock>`.

		.. include:: ../../../links/links.rst
		.. include:: ../../links.rst