fix: header definitions

openedx · Mar 29, 2024 · 944ba86 · 944ba86
1 parent b2b4769
commit 944ba86
Show file tree

Hide file tree

Showing 91 changed files with 786 additions and 813 deletions.
diff --git a/source/community/release_notes/CSMHE/index.rst b/source/community/release_notes/CSMHE/index.rst
@@ -1,7 +1,7 @@
 .. _Replacing CSMH:
 
 Replacing the ``courseware_studentmodulehistory`` Table
-########################################################
+#######################################################
 
 This section describes a change to the ``courseware_studentmodulehistory``
 database table.

diff --git a/source/community/release_notes/quince.rst b/source/community/release_notes/quince.rst
@@ -43,7 +43,7 @@ Administrators & Operators
 **************************
 
 New Learner Home Page
-==================================
+=====================
 
 No longer experimental, the new Learner Home has many of the same features as the old learner dashboard, with some extended functionality and
 performance enhancements.

diff --git a/source/course_ops/concepts/index.rst b/source/course_ops/concepts/index.rst
@@ -1,2 +1,2 @@
 Course Ops: Concepts
-###########################
+####################
diff --git a/source/course_ops/how-tos/index.rst b/source/course_ops/how-tos/index.rst
@@ -1,7 +1,2 @@
 Course Ops: How-tos
-##################################
-
-
-
-
-
+###################
diff --git a/source/course_ops/index.rst b/source/course_ops/index.rst
@@ -1,2 +1,2 @@
 Open edX Course Operators
-#############################
+#########################
diff --git a/source/course_ops/quickstarts/index.rst b/source/course_ops/quickstarts/index.rst
@@ -1,36 +1,19 @@
-
-
-
-
 Course Ops: Quick Start
-######################################
+#######################
 
 .. contents:: Main Tasks
  :local:
  :depth: 1
 
 
-
-
 Set up Cohorts
-****************
-
-
-
+**************
 
 View Grades
-************
-
-
+***********
 
 Assign a Grade
-***************
-
-
+**************
 
 End a Course
-***************
-
-
-
-
+************
diff --git a/source/course_ops/references/index.rst b/source/course_ops/references/index.rst
@@ -1,2 +1,2 @@
 Course Ops: References
-#############################
+######################
diff --git a/source/developers/how-tos/add-sphinx-docs-to-a-repo.rst b/source/developers/how-tos/add-sphinx-docs-to-a-repo.rst
@@ -1,5 +1,5 @@
 How To Add Sphinx Docs to a Repo
-#################################
+################################
 
 .. How-tos should have a short introduction sentence that captures the user's goal and introduces the steps.
 

diff --git a/source/developers/index.rst b/source/developers/index.rst
@@ -1,5 +1,5 @@
 Open edX Developers
-####################
+###################
 
 .. grid:: 1 2 2 2
    :gutter: 3

diff --git a/source/developers/references/developer_guide/analytics.rst b/source/developers/references/developer_guide/analytics.rst
@@ -1,8 +1,8 @@
 .. _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
@@ -11,17 +11,17 @@ 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::
 
@@ -33,15 +33,15 @@ Emitting from client-side JavaScript::
     Logger.log 'some.event.name', 'foo': 'bar'
 
 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``.
 
 Naming Events
-==============
+=============
 
 Event names are intended to be formatted as `.` separated strings and help
 processing of related events. The structure is intended to be
@@ -59,7 +59,7 @@ Examples:
         * 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
@@ -85,7 +85,7 @@ 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

diff --git a/source/developers/references/developer_guide/conventions/django.rst b/source/developers/references/developer_guide/conventions/django.rst
@@ -1,16 +1,16 @@
 .. _Django Good Practices:
 
-*********************
+#####################
 Django Good Practices
-*********************
+#####################
 
 .. contents::
  :local:
  :depth: 2
 
-=======
+*******
 Imports
-=======
+*******
 
 Always import from the root of the project::
 

diff --git a/source/developers/references/developer_guide/conventions/index.rst b/source/developers/references/developer_guide/conventions/index.rst
@@ -1,8 +1,8 @@
 .. _coding_conventions:
 
-##################
+#################
 Writing Good Code
-##################
+#################
 
 .. toctree::
     :maxdepth: 2

diff --git a/source/developers/references/developer_guide/extending_platform/extending.rst b/source/developers/references/developer_guide/extending_platform/extending.rst
@@ -1,9 +1,9 @@
 
 .. _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.

diff --git a/source/developers/references/developer_guide/extending_platform/index.rst b/source/developers/references/developer_guide/extending_platform/index.rst
@@ -1,6 +1,6 @@
-###########################
+##########################
 Extending the edX Platform
-###########################
+##########################
 
 .. toctree::
     :maxdepth: 2

diff --git a/source/developers/references/developer_guide/extending_platform/xblocks.rst b/source/developers/references/developer_guide/extending_platform/xblocks.rst
@@ -1,5 +1,5 @@
 Integrating XBlocks with edx-platform
-=====================================
+#####################################
 
 The edX LMS and Studio have several features that are extensions of the core
 XBlock libraries (https://xblock.readthedocs.io). These features are listed
@@ -44,9 +44,9 @@ handler is executed by the LMS.
 In the future, these are likely to become more formal XBlock services (one
 related to users, and the other to event publishing).
 
-================
+==============
 Class Features
-================
+==============
 
 These are class attributes or functions that can be provided by an XBlock to
 customize behavior in the LMS.
@@ -62,9 +62,9 @@ customize behavior in the LMS.
   ``problem``), and determines which icon appears in edx sequence headers.
   There is currently no way to provide a different icon.
 
-================
+=======
 Grading
-================
+=======
 
 To participate in the course grade, an XBlock should set ``has_score`` to
 ``True``, and should ``publish`` a ``grade`` event whenever the grade changes.
@@ -82,9 +82,9 @@ The grade event represents a grade of ``value/max_value`` for the current user.
 The ``user_id`` field is optional, the currently logged in user's ID will be
 used if it is omitted.
 
-================
+============
 Restrictions
-================
+============
 
 A block cannot modify the value of any field with a scope where the ``user``
 property is ``UserScope.NONE``.
@@ -93,9 +93,9 @@ property is ``UserScope.NONE``.
 Studio
 ******
 
-================
+==============
 Class Features
-================
+==============
 
 * studio_view (XBlock.view): The view used to render an editor in Studio. The
   editor rendering can be completely different from the LMS student_view, and
@@ -110,9 +110,9 @@ Class Features
 * non_editable_metadata_fields (property): A list of ``xblock.fields.Field``
   objects that should not be displayed in the default editing view for Studio.
 
-================
+============
 Restrictions
-================
+============
 
 A block cannot modify the value of any field with a scope where the ``user``
 property is not ``UserScope.NONE``.
@@ -179,9 +179,9 @@ the list of ``ADVANCED_COMPONENT_TYPES`` in
 
 .. _XBlock URL Dev:
 
-**************************************
+*************************************
 Rendering XBlocks with the XBlock URL
-**************************************
+*************************************
 
 The XBlock URL supports HTML rendering of an individual XBlock without the user
 interface of the LMS.

diff --git a/source/developers/references/developer_guide/internationalization/index.rst b/source/developers/references/developer_guide/internationalization/index.rst
@@ -1,6 +1,6 @@
-######################################
+#####################################
 Writing Code for Internationalization
-######################################
+#####################################
 
 .. toctree::
     :maxdepth: 2

diff --git a/...eferences/developer_guide/preventing_xss/preventing_xss_in_django_templates.rst b/...eferences/developer_guide/preventing_xss/preventing_xss_in_django_templates.rst
@@ -1,7 +1,7 @@
 .. _Preventing XSS in Django Templates:
 
 Preventing XSS in Django Templates
-==================================
+##################################
 
 Django Templates are safe-by-default, which means that expressions are HTML-escaped by default. However, there are cases where expressions are not properly escaped by default:
 
@@ -15,7 +15,7 @@ Django Templates are safe-by-default, which means that expressions are HTML-esca
 .. note:: Do not use the `"striptags" filter <https://docs.djangoproject.com/en/dev/ref/templates/builtins/#striptags>`__, which only makes an attempt at stripping HTML. Instead, use the bleach library.
 
 HTML-escaping Translations in Django Templates
-----------------------------------------------
+**********************************************
 
 In Django templates, strings wrapped in ``trans`` and ``blocktrans`` are not automatically escaped, which leads to a vulnerability where translators could include malicious script tags in their translations.
 

diff --git a/...elopers/references/developer_guide/preventing_xss/preventing_xss_strip_tags.rst b/...elopers/references/developer_guide/preventing_xss/preventing_xss_strip_tags.rst
@@ -1,14 +1,14 @@
 .. _Preventing XSS by Stripping HTML Tags:
 
 Preventing XSS by Stripping HTML Tags
-=====================================
+#####################################
 
 .. contents::
    :depth: 2
    :local:
 
 Overview
---------
+********
 
 .. note:: Having server-side HTML data was more likely with our legacy code, but is still possible. We should avoid data with HTML where possible.
 
@@ -22,7 +22,7 @@ In both cases, we use a library called bleach.
 
 
 Mako filters for bleaching
---------------------------
+**************************
 
 At the time of writing this, we do not yet have Mako filters for bleaching. However, that would be very useful. If you need this, please do the following:
 
@@ -33,15 +33,15 @@ At the time of writing this, we do not yet have Mako filters for bleaching. Howe
 3. Update this documentation to detail using the filters.
 
 Strip all HTML tags
--------------------
+*******************
 
 You would typically do this when people have entered HTML tags inside a field in the past, and you no longer want to support HTML, but you also don't want escaped HTML tags to start appearing on the page.
 
 Here is an `example using bleach to strip all
 tags <https://github.com/openedx/edx-platform/blob/a864b450a889df77f1c7379271dc9a80b3c1a8ee/lms/templates/courseware/progress_graph.js#L76>`__.
 
 Strip all but safe HTML tags
-----------------------------
+****************************
 
 You would do this if you in fact want to allow a user to be able to use certain simple HTML tags, like "<br />", in their input.  Use this sparingly.  It is much simpler to deal with plain text fields.
 

diff --git a/source/developers/references/developer_guide/process/contributor.rst b/source/developers/references/developer_guide/process/contributor.rst
@@ -1,6 +1,6 @@
-************
+############
 Contributing
-************
+############
 
 Contributing your custom code to the Open edX project is a two-step process:
 review of your idea by the product team (the Product Review Process),
@@ -14,9 +14,9 @@ Note::
    check with the Product Working Group on the best way to land your fix
    before beginning to write code.
 
-----------------------------------------
+****************************************
 Product Review Process & Product Roadmap
-----------------------------------------
+****************************************
 
 New features added to the Open edX project go through a `Product Review
 Process`_, lead by the `Open edX Product Working Group`_. If you're interested
@@ -46,9 +46,9 @@ what to contribute, check out the roadmap! If you're interested in picking
 up or collaborating on a ticket, join the conversation by adding a comment
 on the ticket.
 
-----------------------------
+****************************
 Getting Preliminary Feedback
-----------------------------
+****************************
 
 It is sometimes useful to submit a pull request even before the code is
 working properly, to make it easier to collect early feedback on your