[OpenMP][Docs] Structure and content for the OpenMP documentation

[jdoerfert]

Summary

This adds some initial content as well as structure to the new OpenMP
Sphinx documentation hosted at http://openmp.llvm.org/docs/ .

The content contains some useful links but most pages are still empty.

This uses a "custom" theme which is a copy of the default "agogo" one
with minor modifications to get a nicer table of content in the sidebar.
This way we can also adjust the theme as we go.

[jdoerfert]

This is how it looks with my Firefox locally:

[jhuber6]

LGTM

[JonChesterfield]

Yep, LG here too. Should check the website publishing infra picks it up post commit.

openmp/docs/ReleaseNotes.rst

 ===========================
-OpenMP 11.0.0 Release Notes
+OpenMP 12.0.0 Release Notes
 ===========================
 
-.. contents::
-    :local:
 
 .. warning::
-   These are in-progress notes for the upcoming LLVM 11.0.0 release.
+   These are in-progress notes for the upcoming LLVM 12.0.0 release.
    Release notes for previous releases can be found on
    `the Download Page <https://releases.llvm.org/download.html>`_.
    
+
 Introduction
 ============
 
-This document contains the release notes for the OpenMP runtime, release 11.0.0.
+This document contains the release notes for the OpenMP runtime, release 12.0.0.
 Here we describe the status of openmp, including major improvements
 from the previous release. All openmp releases may be downloaded
 from the `LLVM releases web site <https://llvm.org/releases/>`_.
 
 Non-comprehensive list of changes in this release
 =================================================
 
-5.0 features
-------------
-
-* ...
-
-5.1 features
-------------
-
-* ...
-
-OMPT Improvements
------------------
-
-* Added OMPT callbacks for doacross loops, detached tasks
-* Added handling for mutexinoutset dependencies
-
-OMPT-based Tools
-----------------
-
-* Added ompt-multiplex.h as a header-only OMPT-tool to support nesting of OMPT
-  tools. (see openmp/tools/multiplex)
 

openmp/docs/SupportAndFAQ.rst

+Support And FAQ
+===============
+
+

openmp/docs/_themes/llvm-openmp-theme/layout.html

+{#
+    llvm-openmp-theme/layout.html
+    ~~~~~~~~~~~~~~~~~
+
+    Sphinx layout template for LLVM/OpenMP which as an almost identical clone
+    of the agogo theme, originally written by Andi Albrecht.
+
+    :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+#}
+{%- extends "basic/layout.html" %}
+
+{% block header %}
+    <div class="header-wrapper" role="banner">
+      <div class="header">
+        {%- if logo %}
+          <p class="logo"><a href="{{ pathto(master_doc)|e }}">
+            <img class="logo" src="{{ pathto('_static/' + logo, 1)|e }}" alt="Logo"/>
+          </a></p>
+        {%- endif %}
+        {%- block headertitle %}
+        <div class="headertitle"><a
+          href="{{ pathto(master_doc)|e }}">{{ shorttitle|e }}</a></div>
+        {%- endblock %}
+        <div class="rel" role="navigation" aria-label="related navigation">
+          <a href="{{ pathto('index') }}" title="LLVM OpenMP Documentation">HOME</a>
+          {{ reldelim2 }}
+          {%- for rellink in rellinks|reverse %}
+          <a href="{{ pathto(rellink[0])|e }}" title="{{ rellink[1]|striptags|e }}"
+             {{ accesskey(rellink[2]) }}>{{ rellink[3] }}</a>
+          {%- if not loop.last %}{{ reldelim2 }}{% endif %}
+          {%- endfor %}
+        </div>
+       </div>
+    </div>
+{% endblock %}
+
+
+{%- macro llvm_openmp_sidebar() %}
+          {%- block sidebartoc %}
+          <h3>{{ _('Table of Contents') }}</h3>
+          {{ toctree(includehidden=True, titles_only=True, maxdepth=2) }}
+          {%- endblock %}
+          {%- block sidebarsearch %}
+          <div role="search">
+            <h3 style="margin-top: 1.5em;">{{ _('Search') }}</h3>
+            <form class="search" action="{{ pathto('search') }}" method="get">
+                <input type="text" name="q" />
+                <input type="submit" value="{{ _('Go') }}" />
+            </form>
+          </div>
+          {%- endblock %}
+{% endmacro %}
+
+{% block content %}
+    <div class="content-wrapper">
+      <div class="content">
+        {%- if not theme_rightsidebar|tobool %}
+        <div class="sidebar">
+          {{ llvm_openmp_sidebar() }}
+        </div>
+        {%- endif %}
+        <div class="document">
+          {%- block document %}
+            {{ super() }}
+          {%- endblock %}
+        </div>
+        {%- if theme_rightsidebar|tobool %}
+        <div class="sidebar">
+          {{ llvm_openmp_sidebar() }}
+        </div>
+        {%- endif %}
+        <div class="clearer"></div>
+      </div>
+    </div>
+{% endblock %}
+
+{% block footer %}
+    <div class="footer-wrapper">
+      <div class="footer">
+        <div class="left">
+          <div role="navigation" aria-label="related navigaton">
+            <a href="{{ pathto('index') }}" title="LLVM OpenMP Documentation">HOME</a>
+            {{ reldelim2 }}
+            {%- for rellink in rellinks|reverse %}
+            <a href="{{ pathto(rellink[0])|e }}" title="{{ rellink[1]|striptags|e }}"
+              {{ accesskey(rellink[2]) }}>{{ rellink[3] }}</a>
+            {%- if not loop.last %}{{ reldelim2 }}{% endif %}
+            {%- endfor %}
+          </div>
+          <div role="note" aria-label="source link">
+            {%- if show_source and has_source and sourcename %}
+              <br/>
+              <a href="{{ pathto('_sources/' + sourcename, true)|e }}"
+                rel="nofollow">{{ _('Show Source') }}</a>
+            {%- endif %}
+          </div>
+        </div>
+
+        <div class="right">
+          {{ super() }}
+        </div>
+        <div class="clearer"></div>
+      </div>
+    </div>
+{% endblock %}
+
+{% block relbar1 %}{% endblock %}
+{% block relbar2 %}{% endblock %}

openmp/docs/_themes/llvm-openmp-theme/static/agogo.css_t

+/*
+ * agogo.css_t
+ * ~~~~~~~~~~~
+ *
+ * Sphinx stylesheet -- agogo theme.
+ *
+ * :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+* {
+  margin: 0px;
+  padding: 0px;
+}
+
+body {
+  font-family: {{ theme_bodyfont }};
+  line-height: 1.4em;
+  color: black;
+  background-color: {{ theme_bgcolor }};
+}
+
+
+/* Page layout */
+
+div.header, div.content, div.footer {
+  width: {{ theme_pagewidth }};
+  margin-left: auto;
+  margin-right: auto;
+}
+
+div.header-wrapper {
+  background: {{ theme_headerbg }};
+  border-bottom: 3px solid #2e3436;
+}
+
+
+/* Default body styles */
+a {
+  color: {{ theme_linkcolor }};
+}
+
+div.bodywrapper a, div.footer a {
+  text-decoration: underline;
+}
+
+.clearer {
+  clear: both;
+}
+
+.left {
+  float: left;
+}
+
+.right {
+  float: right;
+}
+
+.line-block {
+    display: block;
+    margin-top: 1em;
+    margin-bottom: 1em;
+}
+
+.line-block .line-block {
+    margin-top: 0;
+    margin-bottom: 0;
+    margin-left: 1.5em;
+}
+
+h1, h2, h3, h4 {
+  font-family: {{ theme_headerfont }};
+  font-weight: normal;
+  color: {{ theme_headercolor2 }};
+  margin-bottom: .8em;
+}
+
+h1 {
+  color: {{ theme_headercolor1 }};
+}
+
+h2 {
+  padding-bottom: .5em;
+  border-bottom: 1px solid {{ theme_headercolor2 }};
+}
+
+a.headerlink {
+  visibility: hidden;
+  color: #dddddd;
+  padding-left: .3em;
+}
+
+h1:hover > a.headerlink,
+h2:hover > a.headerlink,
+h3:hover > a.headerlink,
+h4:hover > a.headerlink,
+h5:hover > a.headerlink,
+h6:hover > a.headerlink,
+dt:hover > a.headerlink,
+caption:hover > a.headerlink,
+p.caption:hover > a.headerlink,
+div.code-block-caption:hover > a.headerlink {
+  visibility: visible;
+}
+
+img {
+  border: 0;
+}
+
+div.admonition {
+  margin-top: 10px;
+  margin-bottom: 10px;
+  padding: 2px 7px 1px 7px;
+  border-left: 0.2em solid black;
+}
+
+p.admonition-title {
+  margin: 0px 10px 5px 0px;
+  font-weight: bold;
+}
+
+dt:target, .highlighted {
+  background-color: #fbe54e;
+}
+
+/* Header */
+
+div.header {
+  padding-top: 10px;
+  padding-bottom: 10px;
+}
+
+div.header .headertitle {
+  font-family: {{ theme_headerfont }};
+  font-weight: normal;
+  font-size: 180%;
+  letter-spacing: .08em;
+  margin-bottom: .8em;
+}
+
+div.header .headertitle a {
+  color: white;
+}
+
+div.header div.rel {
+  margin-top: 1em;
+}
+
+div.header div.rel a {
+  color: {{ theme_headerlinkcolor }};
+  letter-spacing: .1em;
+  text-transform: uppercase;
+}
+
+p.logo {
+    float: right;
+}
+
+img.logo {
+    border: 0;
+}
+
+
+/* Content */
+div.content-wrapper {
+  background-color: white;
+  padding-top: 20px;
+  padding-bottom: 20px;
+}
+
+div.document {
+  width: {{ theme_documentwidth }};
+  float: left;
+}
+
+div.body {
+  {%- if theme_rightsidebar|tobool %}
+  padding-right: 2em;
+  {%- else %}
+  padding-left: 2em;
+  {% endif %}
+  text-align: {{ theme_textalign }};
+}
+
+div.document h1 {
+  line-height: 120%;
+}
+
+div.document ul {
+  margin: 1.5em;
+  list-style-type: square;
+}
+
+div.document dd {
+  margin-left: 1.2em;
+  margin-top: .4em;
+  margin-bottom: 1em;
+}
+
+div.document .section {
+  margin-top: 1.7em;
+}
+div.document .section:first-child {
+  margin-top: 0px;
+}
+
+div.document div.highlight {
+  padding: 3px;
+  border-top: 2px solid #dddddd;
+  border-bottom: 2px solid #dddddd;
+  margin-top: .8em;
+  margin-bottom: .8em;
+}
+
+div.document div.literal-block-wrapper {
+  margin-top: .8em;
+  margin-bottom: .8em;
+}
+
+div.document div.literal-block-wrapper div.highlight {
+  margin: 0;
+}
+
+div.document div.code-block-caption span.caption-number {
+    padding: 0.1em 0.3em;
+    font-style: italic;
+}
+
+div.document div.code-block-caption span.caption-text {
+}
+
+div.document h2 {
+  margin-top: .7em;
+}
+
+div.document p {
+  margin-bottom: .5em;
+}
+
+div.document li.toctree-l1 {
+  margin-bottom: 1em;
+}
+
+div.document .descname {
+  font-weight: bold;
+}
+
+div.document .sig-paren {
+    font-size: larger;
+}
+
+div.document .docutils.literal {
+  background-color: #eeeeec;
+  padding: 1px;
+}
+
+div.document .docutils.xref.literal {
+  background-color: transparent;
+  padding: 0px;
+}
+
+div.document blockquote {
+  margin: 1em;
+}
+
+div.document ol {
+  margin: 1.5em;
+}
+
+
+/* Sidebar */
+
+div.sidebar {
+  width: {{ theme_sidebarwidth|todim }};
+  {%- if theme_rightsidebar|tobool %}
+  float: right;
+  {%- else %}
+  float: left;
+  {%- endif %}
+  font-size: .9em;
+}
+
+div.sidebar a, div.header a {
+  text-decoration: none;
+}
+
+div.sidebar a:hover, div.header a:hover {
+  text-decoration: underline;
+}
+
+div.sidebar h3 {
+  color: #2e3436;
+  text-transform: uppercase;
+  font-size: 130%;
+  letter-spacing: .1em;
+}
+
+div.sidebar ul {
+  list-style-type: none;
+}
+
+div.sidebar li.toctree-l1 a {
+  display: block;
+  padding: 1px;
+  border: 1px solid #dddddd;
+  background-color: #eeeeec;
+  margin-bottom: .4em;
+  padding-left: 3px;
+  color: #2e3436;
+}
+
+div.sidebar li.toctree-l2 a {
+  background-color: transparent;
+  border: none;
+  margin-left: 1em;
+  border-bottom: 1px solid #dddddd;
+}
+
+div.sidebar li.toctree-l3 a {
+  background-color: transparent;
+  border: none;
+  margin-left: 2em;
+  border-bottom: 1px solid #dddddd;
+}
+
+div.sidebar li.toctree-l2:last-child a {
+  border-bottom: none;
+}
+
+div.sidebar li.toctree-l1.current a {
+  border-right: 5px solid {{ theme_headerlinkcolor }};
+}
+
+div.sidebar li.toctree-l1.current li.toctree-l2 a {
+  border-right: none;
+}
+
+div.sidebar input[type="text"] {
+  width: 170px;
+}
+
+div.sidebar input[type="submit"] {
+  width: 30px;
+}
+
+
+/* Footer */
+
+div.footer-wrapper {
+  background: {{ theme_footerbg }};
+  border-top: 4px solid #babdb6;
+  padding-top: 10px;
+  padding-bottom: 10px;
+  min-height: 80px;
+}
+
+div.footer, div.footer a {
+  color: #888a85;
+}
+
+div.footer .right {
+  text-align: right;
+}
+
+div.footer .left {
+  text-transform: uppercase;
+}
+
+
+/* Styles copied from basic theme */
+
+img.align-left, .figure.align-left, object.align-left {
+    clear: left;
+    float: left;
+    margin-right: 1em;
+}
+
+img.align-right, .figure.align-right, object.align-right {
+    clear: right;
+    float: right;
+    margin-left: 1em;
+}
+
+img.align-center, .figure.align-center, object.align-center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.align-left {
+    text-align: left;
+}
+
+.align-center {
+    text-align: center;
+}
+
+.align-right {
+    text-align: right;
+}
+
+table caption span.caption-number {
+    font-style: italic;
+}
+
+table caption span.caption-text {
+}
+
+div.figure p.caption span.caption-number {
+    font-style: italic;
+}
+
+div.figure p.caption span.caption-text {
+}
+
+/* -- search page ----------------------------------------------------------- */
+
+ul.search {
+    margin: 10px 0 0 20px;
+    padding: 0;
+}
+
+ul.search li {
+    padding: 5px 0 5px 20px;
+    background-image: url(file.png);
+    background-repeat: no-repeat;
+    background-position: 0 7px;
+}
+
+ul.search li a {
+    font-weight: bold;
+}
+
+ul.search li div.context {
+    color: #888;
+    margin: 2px 0 0 30px;
+    text-align: left;
+}
+
+ul.keywordmatches li.goodmatch a {
+    font-weight: bold;
+}
+
+/* -- index page ------------------------------------------------------------ */
+
+table.contentstable {
+    width: 90%;
+}
+
+table.contentstable p.biglink {
+    line-height: 150%;
+}
+
+a.biglink {
+    font-size: 1.3em;
+}
+
+span.linkdescr {
+    font-style: italic;
+    padding-top: 5px;
+    font-size: 90%;
+}
+
+/* -- general index --------------------------------------------------------- */
+
+table.indextable td {
+    text-align: left;
+    vertical-align: top;
+}
+
+table.indextable ul {
+    margin-top: 0;
+    margin-bottom: 0;
+    list-style-type: none;
+}
+
+table.indextable > tbody > tr > td > ul {
+    padding-left: 0em;
+}
+
+table.indextable tr.pcap {
+    height: 10px;
+}
+
+table.indextable tr.cap {
+    margin-top: 10px;
+    background-color: #f2f2f2;
+}
+
+img.toggler {
+    margin-right: 3px;
+    margin-top: 3px;
+    cursor: pointer;
+}
+
+/* -- domain module index --------------------------------------------------- */
+
+table.modindextable td {
+    padding: 2px;
+    border-collapse: collapse;
+}
+
+/* -- viewcode extension ---------------------------------------------------- */
+
+.viewcode-link {
+    float: right;
+}
+
+.viewcode-back {
+    float: right;
+    font-family:: {{ theme_bodyfont }};
+}
+
+div.viewcode-block:target {
+    margin: -1px -3px;
+    padding: 0 3px;
+    background-color: #f4debf;
+    border-top: 1px solid #ac9;
+    border-bottom: 1px solid #ac9;
+}
+
+div.code-block-caption {
+    background-color: #ddd;
+    color: #333;
+    padding: 2px 5px;
+    font-size: small;
+}
+
+/* -- math display ---------------------------------------------------------- */
+
+div.body div.math p {
+    text-align: center;
+}
+
+span.eqno {
+    float: right;
+}

openmp/docs/_themes/llvm-openmp-theme/theme.conf

+[theme]
+inherit = basic
+stylesheet = agogo.css
+pygments_style = tango
+
+[options]
+bodyfont = "Verdana", Arial, sans-serif
+headerfont = "Georgia", "Times New Roman", serif
+pagewidth = 70em
+documentwidth = 50em
+rightsidebar = true
+sidebarwidth = 20em
+bgcolor = #eeeeec
+headerbg = #555573 url(bgtop.png) top left repeat-x
+footerbg = url(bgfooter.png) top left repeat-x
+linkcolor = #ce5c00
+headercolor1 = #204a87
+headercolor2 = #3465a4
+headerlinkcolor = #fcaf3e
+textalign = justify

openmp/docs/conf.py

 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
-project = u'LLVM OpenMP'
-copyright = u'2013-%d, LLVM OpenMP' % date.today().year
+project = u'LLVM/OpenMP'
+copyright = u'2013-%d, LLVM/OpenMP' % date.today().year
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents. These are currently set to zero because we don't use them.
 # Should somebody consider in the future to change them, they need to be updated
 # everytime a new release comes out.
 #
 # The short version.

 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
 
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'llvm-theme'
+html_theme = 'llvm-openmp-theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 # html_theme_options = { 'font_size': '11pt' }
 
 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = ["_themes"]

 
 # Additional stuff for the LaTeX preamble.
 #'preamble': '',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'OpenMP.tex', u'LLVM OpenMP Documentation',
-   u'LLVM OpenMP', 'manual'),
+  ('index', 'OpenMP.tex', u'LLVM/OpenMP Documentation',
+   u'LLVM/OpenMP', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 #latex_logo = None
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.

 
 
 # -- Options for Texinfo output ------------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'LLVM OpenMP', u'LLVM OpenMP Documentation',
-   u'LLVM OpenMP', 'LLVM OpenMP', 'One line description of project.',
+  ('index', 'LLVM/OpenMP', u'LLVM/OpenMP Documentation',
+   u'LLVM/OpenMP', 'LLVM/OpenMP', 'One line description of project.',
    'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.
 #texinfo_appendices = []
 
 # If false, no module index is generated.
 #texinfo_domain_indices = True
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'

openmp/docs/design/GPUGenericMode.rst

+OpenMP Target Offloading --- Generic Mode
+=========================================

openmp/docs/design/GPUSPMDMode.rst

+OpenMP Target Offloading --- SPMD Mode
+======================================

openmp/docs/design/Offloading.rst

+OpenMP in LLVM --- Offloading Design
+====================================
+
+.. toctree::
+   :glob:
+   :hidden:
+   :maxdepth: 1
+
+   GPUSPMDMode
+   GPUGenericMode
+

openmp/docs/design/Overview.rst

+OpenMP in LLVM --- Design Overview
+==================================
+
+
+
+.. toctree::
+   :glob:
+   :hidden:
+   :maxdepth: 1
+
+   Runtimes
+   Offloading
+

openmp/docs/design/Runtimes.rst

+.. _openmp_runtimes:
+
+LLVM/OpenMP Runtimes
+====================
+
+There are four distinct types of LLVM/OpenMP runtimes 
+
+LLVM/OpenMP Host Runtime (``libomp``)
+-------------------------------------
+
+An `early (2015) design document <https://openmp.llvm.org/Reference.pdf>`_ for
+the LLVM/OpenMP host runtime, aka.  `libomp.so`, is available as a `pdf
+<https://openmp.llvm.org/Reference.pdf>`_.
+
+
+LLVM/OpenMP Target Host Runtime (``libomptarget``)
+--------------------------------------------------
+
+LLVM/OpenMP Target Host Runtime Plugins (``libomptarget.rtl.XXXX``)
+-------------------------------------------------------------------
+
+LLVM/OpenMP Target Device Runtime (``libomptarget-ARCH-SUBARCH.bc``)
+--------------------------------------------------------------------
+

openmp/docs/index.rst

-About
-=====
+.. title:: Welcome to the documentation of OpenMP in LLVM!
 
-Support for the OpenMP parallel programming API in the LLVM compiler
-infrastructure. Here you will find helpful links to OpenMP library documentation
-and other resources.
+.. note::
+   This document is a work in progress and most of the expected content is not
+   yet available. While you can expect changes, we always welcome feedback and
+   additions. Please contact, e.g., through ``[e-mail]``.
 
-LLVM OpenMP Design & Overview
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   LLVM/OpenMP Documentation <self>
+
+
+LLVM/OpenMP Design & Overview
 =============================
 
-This describes the design of the `LLVM OpenMP Runtime Library`_
+OpenMP impacts various parts of the LLVM project, from the frontends (`Clang
+<https://clang.llvm.org/docs/OpenMPSupport.html>`_ and Flang), through
+middle-end :ref:`optimizations <llvm_openmp_optimizations>`, up to the
+multitude of available :ref:`OpenMP runtimes <openmp_runtimes>`.
 
-.. _`LLVM OpenMP Runtime Library`: https://openmp.llvm.org/Reference.pdf
+A high-level overview of OpenMP in LLVM can be found :doc:`here <design/Overview>`.
 
-Release Notes
-=============
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   design/Overview
 
-Current OpenMP release notes.
+
+LLVM/OpenMP Optimizations
+=========================
+
+LLVM, since `version 11 <https://releases.llvm.org/download.html#11.0.0>`_ (12 Oct
+2020), has an :doc:`OpenMP-Aware optimization pass <optimizations/OpenMPOpt>`
+as well as the ability to :doc:`perform "scalar optimizations" across OpenMP region
+boundaries <optimizations/OpenMPUnawareOptimizations>`.
+
+In-depth discussion of the topic can be found :doc:`here <optimizations/Overview>`.
 
 .. toctree::
    :hidden:
+   :maxdepth: 1
+
+   optimizations/Overview
+
+LLVM/OpenMP Optimization Remarks
+================================
+
+LLVM has an elaborate ecosystem around `analysis and optimization remarks
+<https://llvm.org/docs/Remarks.html>`_ issues during
+compilation. The remarks can be enabled from the clang frontend `[1]`_ `[2]`_
+in various formats `[3]`_ `[4]`_ to be used by tools, i.a., `opt-viewer` or
+`llvm-opt-report` (dated).
+
+The OpenMP optimizations in LLVM have been developed with remark support as a
+priority. For a list of OpenMP specific remarks and more information on them,
+please refer to :doc:`remarks/OptimizationRemarks`.
+
+
+.. _`[1]`: https://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports
+.. _`[2]`: https://clang.llvm.org/docs/ClangCommandLineReference.html#diagnostic-flags
+.. _`[3]`: https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-foptimization-record-file
+.. _`[4]`: https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang1-fsave-optimization-record
+
++ `[1]`_ https://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports
++ `[2]`_ https://clang.llvm.org/docs/ClangCommandLineReference.html#diagnostic-flags
++ `[3]`_ https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-foptimization-record-file
++ `[4]`_ https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang1-fsave-optimization-record
+
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   remarks/OptimizationRemarks
+
+
+Support & Frequently Asked Questions (FAQ)
+==========================================
+
+Dealing with OpenMP can be complicated. For help with the setup of an OpenMP
+(offload) capable compiler toolchain, its usage, and common problems, consult
+the :doc:`Support and FAQ <SupportAndFAQ>` page.
+
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   SupportAndFAQ
 
-   ReleaseNotes
+Release Notes
+=============
+
+The current (in-progress) release notes can be found :doc:`here <ReleaseNotes>` while
+release notes for releases, starting with LLVM 12, will be available on `the
+Download Page <https://releases.llvm.org/download.html>`_.
+
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
 
-* :doc:`ReleaseNotes`
+   In-Progress ReleaseNotes <ReleaseNotes>

openmp/docs/optimizations/OpenMPOpt.rst

+OpenMP-Aware Optimizations
+==========================
+
+OpenMPOpt
+---------

openmp/docs/optimizations/OpenMPUnawareOptimizations.rst

+OpenMP-Unaware Optimizations
+============================

openmp/docs/optimizations/Overview.rst

+.. _llvm_openmp_optimizations:
+
+OpenMP Optimizations in LLVM
+============================
+
+LLVM, since `version 11 <https://releases.llvm.org/download.html#11.0.0>`_ (12 Oct
+2020), has an :doc:`OpenMP-Aware optimization pass <OpenMPOpt>`
+as well as the ability to :doc:`perform "scalar optimizations" across OpenMP region
+boundaries <OpenMPUnawareOptimizations>`.
+
+.. toctree::
+   :glob:
+   :hidden:
+   :titlesonly:
+   :maxdepth: 1
+
+   OpenMPOpt
+   OpenMPUnawareOptimizations
+

openmp/docs/remarks/OptimizationRemarks.rst

+OpenMP Optimization Remarks
+===========================