Page MenuHomePhabricator

[Flang] Add GettingInvolved documentation page and sidebar.
ClosedPublic

Authored by sameeranjoshi on Sep 7 2020, 10:14 PM.

Details

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

Diff Detail

Event Timeline

sameeranjoshi created this revision.Sep 7 2020, 10:14 PM
Herald added a project: Restricted Project. · View Herald Transcript
sameeranjoshi requested review of this revision.Sep 7 2020, 10:14 PM
richard.barton.arm requested changes to this revision.Sep 11 2020, 8:11 AM

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.

This revision now requires changes to proceed.Sep 11 2020, 8:11 AM
sameeranjoshi marked 13 inline comments as done.Sep 13 2020, 10:44 PM
sameeranjoshi added inline comments.
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 requested changes to this revision.Sep 14 2020, 1:00 AM
richard.barton.arm added inline comments.
flang/docs/GettingInvolved.md
57

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

65

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
26

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.

This revision now requires changes to proceed.Sep 14 2020, 1:00 AM
sameeranjoshi edited the summary of this revision. (Show Details)

Update with changes.

LGTM - thanks for this.

This revision is now accepted and ready to land.Sep 15 2020, 5:27 AM

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

@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?

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