[Flang] Add GettingInvolved documentation page and sidebar.

[sameeranjoshi]

Summary

Adds a new GettingInvolved page to documentation which provides details about
mailing list, chats and calls.

Adds a sidebar page which provides common links on
all documentation pages.
The links include:

• Getting Started
• Getting Involved
• Github Repository
• Bug Reports
• Code Review

Depends on https://reviews.llvm.org/D87242

[richard.barton.arm]

Nice one - a good addition to the docs, IMO.

I have requested some detail changes.

flang/docs/GettingInvolved.md

2

The heading depths need to be corrected for this to display well in the new index file toctrees. Needs to be # for the top-level section and ## for the subsections.

5

^The Flang Project...

6

or

15

There are some plain text references to Flang (capital F) and flang (lower-case f). Suggest to standardise on one - probably Flang.

43

Missing line about the minutes - these are sent by email to flang-dev.

50

*Doc (singular)

50

minutes or agenda

52

I don't think we should include this as it could be confusing. I suggest keeping this section for LLVM Flang business only.

64

Please add some text like the other ones - "Minutes are here ..." or something.

68

Suggest to delete the Teams reference. The conf software is not relevant to this sentence and might change in future as trends change.

68

Missing sentence on the purpose of the call.

69

OCD: it would be nice for these all to line up. The other say:

• Purpose of the call
• How to join
• Time of the call
• Minutes

This one has it in a different order. :-(

flang/docs/_templates/indexsidebar.html

25

Does this comment mean buildbots? Could we link to http://lab.llvm.org:8011/console here?

flang/docs/conf.py

173

Shouldn't commit commented out lines.

[sameeranjoshi]

flang/docs/_templates/indexsidebar.html

25

We need something like http://llvm.org/doxygen/index.html
From what I understand I think we need one of the buildbots to builds documentation and host them somewhere.
Not completely sure how this is handled in LLVM.

[richard.barton.arm]

flang/docs/GettingInvolved.md

56

I think the original version is correct - this is on the opposite week the the above community biweekly.

64

Doc (singular)

flang/docs/_templates/indexsidebar.html

25

Understood. Perhaps we could ask the owner of that bot to enable Flang in the build?

No need for that to block progress on this patch though. Happy to go with the TODO for now.

flang/docs/index.md

25

I think this document should be the first document in the "Contributing to Flang" section, rather than as a separate toctree below it. It seems like the perfect intro to folks wanting to work on Flang.

[sameeranjoshi]

Update with changes.

[richard.barton.arm]

LGTM - thanks for this.

[richard.barton.arm]

@sameeranjoshi I see this merged but I don't see any changes to the sidebar in my local build.

[sameeranjoshi]

In D87270#2275939, @richard.barton.arm wrote:

@sameeranjoshi I see this merged but I don't see any changes to the sidebar in my local build.

I cloned the latest sources.
b42fa0c040961b3704e826ddc969c0e98238c3ba
I built it and I see the changes.

My configs are

sphinx-build 3.2.1
Name: recommonmark
Version: 0.5.0

and cmake commands are

cmake -GNinja -DCMAKE_BUILD_TYPE="Release" -DLLVM_TARGETS_TO_BUILD=host -DLLVM_ENABLE_PROJECTS="flang"  -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF  llvm-project/llvm/

ninja docs-flang-html

@richard.barton.arm Brower caching might be issue in your case?

[richard.barton.arm]

Sorry @sameeranjoshi - you are right, the changes look good.

[hans]

Cherry-picked to 11.x as 4fe4e35452ef17ce3db08b080e3b0642d36c5094.

flang/docs/GettingInvolved.md

+<!--===- docs/GettingInvolved.md
+
+   Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+   See https://llvm.org/LICENSE.txt for license information.
+   SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+-->
+# Getting Involved
+
+```eval_rst
+.. contents::
+   :local:
+```
+
+The Flang Project welcomes contributions of all kinds.
+Please feel free to join the mailing list or the slack channel for discussions related to development of Flang.
+To understand the status of various developments in Flang please join the respective call.
+
+## Mailing Lists
+
+[Developer's List (flang-dev)](http://lists.llvm.org/mailman/listinfo/flang-dev)
+
+  This list is for people who want to be included in technical discussions related to Flang. People post to this list when they have questions about writing code
+  for or using the Flang tools. It is relatively low volume.
+
+
+[Commits Archive (flang-commits)](http://lists.llvm.org/pipermail/flang-commits)
+
+  This list contains all commit messages that are made when Flang developers
+  commit code changes to the repository. It also serves as a forum for
+  patch review (i.e. send patches here). It is useful for those who want to
+  stay on the bleeding edge of Flang development. This list is high
+  volume.
+
+## Chat
+
+### Flang Slack Workspace
+
+-   There is a Slack workspace dedicated to Flang.
+-   There are a number of topic-oriented channels available (e.g., #driver, #f18-semantics, #fir).
+-   Add yourself via the *[invitation link](https://join.slack.com/t/flang-compiler/shared_invite/zt-2pcn51lh-VrRQL_YUOkxA_1CEfMGQhw "title")*
+
+## Calls
+
+### Flang Community Biweekly Call
+
+-   General updates on the Flang Project, both LLVM Flang and current Flang.
+-   Join [Flang Community Biweekly Call](https://nvmeet.webex.com/nvmeet/j.php?MTID=mb4edb8c799f69ec2dc0554acc969a162)
+-   Time: The call is held every other Wednesday 8:80 Pacific Time in the same week as the Flang Community Technical Biweekly Call.
+-   Minutes: They are sent to [flang-dev](http://lists.llvm.org/mailman/listinfo/flang-dev). Search for `Flang Biweekly Sync - Notes`.
+
+### Flang Community Technical Biweekly Call
+
+-   Technical topics call.
+-   Join [Flang Community Technical Biweekly Call](https://bluejeans.com/625064848?src=join_info)
+-   Time: Happens every other Monday 8:30 Pacific Time in same week as the Flang Community Biweekly Call.
+-   The agenda is in this [Google Doc](https://docs.google.com/document/d/1Z2U5UAtJ-Dag5wlMaLaW1KRmNgENNAYynJqLW2j2AZQ/).
+
+### LLVM Alias Analysis Technical Call
+
+-   For people working on improvements to LLVM alias analysis.
+-   Join [LLVM Alias Analysis Technical Call](https://bluejeans.com/101176001?src=join_info)
+-   Time: Tuesdays 10:00 AM Pacific Time, every 4 weeks.
+-   The agenda is in this [Google Docs](https://docs.google.com/document/d/1ybwEKDVtIbhIhK50qYtwKsL50K-NvB6LfuBsfepBZ9Y/).
+
+### OpenMP Technical Call
+
+-   Development updates on OpenMP and OpenACC in the Flang Project.
+-   Join [OpenMP Technical Call](https://bit.ly/39eQW3o)
+-   Time: Weekly call on every Thursdays 8:00 AM Pacific time.
+-   Meeting minutes are [here](https://docs.google.com/document/d/1yA-MeJf6RYY-ZXpdol0t7YoDoqtwAyBhFLr5thu5pFI).
+-   Status tracking [page](https://docs.google.com/spreadsheets/d/1FvHPuSkGbl4mQZRAwCIndvQx9dQboffiD-xD0oqxgU0/edit#gid=0).

flang/docs/_templates/indexsidebar.html

+{# This template defines sidebar which can be used to provide common links on
+   all documentation pages. #}
+
+<h3>Documentation</h3>
+
+<ul class="want-points">
+    <li><a href="https://github.com/llvm/llvm-project/blob/master/flang/README.md#getting-started">Getting Started</a></li>
+</ul>
+
+<h3>Getting Involved</h3>
+<! TODO: Point links to website(flang.llvm.org) and not github once webpage comes up.>
+<ul class="want-points">
+    <li><a href="https://github.com/llvm/llvm-project/blob/master/flang/docs/GettingInvolved.md#mailing-lists">Mailing Lists</a></li>
+    <li><a href="https://github.com/llvm/llvm-project/blob/master/flang/docs/GettingInvolved.md#chat">Slack</a></li>
+    <li><a href="https://github.com/llvm/llvm-project/blob/master/flang/docs/GettingInvolved.md#calls">Calls</a></li>
+</ul>
+
+<h3>Additional Links</h3>
+
+<ul class="want-points">
+    <li><a href="https://github.com/llvm/llvm-project/tree/master/flang/">Github Repository</a></li>
+    <li><a href="https://bugs.llvm.org/">Bug Reports</a></li>
+    <li><a href="https://reviews.llvm.org/">Code Review</a></li>
+<! TODO: Have the bots setup first>
+    <li><a href="#">Doxygen API</a></li>
+</ul>

flang/docs/_templates/layout.html

+{% extends "!layout.html" %}
+
+{% block extrahead %}
+<style type="text/css">
+  table.right { float: right; margin-left: 20px; }
+  table.right td { border: 1px solid #ccc; }
+</style>
+{% endblock %}
+
+{% block rootrellink %}
+<! TODO: Change the webpage  >
+  <li><a href="https://flang.llvm.org">Flang Home</a>&nbsp;|&nbsp;</li>
+  <li><a href="{{ pathto('index') }}">Documentation</a>&raquo;</li>
+{% endblock %}

flang/docs/conf.py

 # using the given strftime format.
 html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {
+    '**': [
+        'indexsidebar.html',
+        'searchbox.html',
+    ]
+}
+
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 #html_additional_pages = {}
 
 # If false, no module index is generated.
 #html_domain_indices = True
 

flang/docs/index.md

.. toctree::
 
    FortranForCProgrammers
    C++style
    C++17
    PullRequestChecklist
    ImplementingASemanticCheck
 ```
 
+# Getting Involved
+
+```eval_rst
+.. toctree::
+   :titlesonly:
+
+   GettingInvolved
+```
+
 # Design Documents
 
 ```eval_rst
 .. toctree::
    :titlesonly:
 
    Overview
    Preprocessing