From a617867a4592a63921279a188a936e77d03d58f8 Mon Sep 17 00:00:00 2001 From: Artem Titov Date: Mon, 30 Jan 2023 10:51:01 +0000 Subject: [PATCH] Reland "Migrate WebRTC documentation to new renderer" This reverts commit 0f2ce5cc1c779f9bf33f51f29bfffbcbe105d1b1. Reason for revert: Downstream infrastructure should be ready now Original change's description: > Revert "Migrate WebRTC documentation to new renderer" > > This reverts commit 3eceaf46695518f25bef43f155f82ed174827197. > > Reason for revert: > > Original change's description: > > Migrate WebRTC documentation to new renderer > > > > Bug: b/258408932 > > Change-Id: Ib96f39fe0c3912f9746bcc09d079097a145d6115 > > Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/290987 > > Reviewed-by: Harald Alvestrand > > Commit-Queue: Artem Titov > > Cr-Commit-Position: refs/heads/main@{#39205} > > Bug: b/258408932 > Change-Id: I16cb4088bee3fc15c2bb88bd692c592b3a7db9fe > No-Presubmit: true > No-Tree-Checks: true > No-Try: true > Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/291560 > Bot-Commit: rubber-stamper@appspot.gserviceaccount.com > Owners-Override: Artem Titov > Commit-Queue: Artem Titov > Cr-Commit-Position: refs/heads/main@{#39209} Bug: b/258408932 Change-Id: Ia172e4a6ad1cc7953b48eed08776e9d1e44eb074 Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/291660 Owners-Override: Artem Titov Reviewed-by: Harald Alvestrand Bot-Commit: rubber-stamper@appspot.gserviceaccount.com Commit-Queue: Artem Titov Cr-Commit-Position: refs/heads/main@{#39231} --- CODE_OF_CONDUCT.md | 3 ++ api/README.md | 7 +++-- api/g3doc/index.md | 4 +-- api/g3doc/threading_design.md | 5 ++-- g3doc.lua | 1 - g3doc/abseil-in-webrtc.md | 6 ++-- g3doc/become_a_committer.md | 6 ++-- g3doc/field-trials.md | 6 ++-- g3doc/g3doc.lua | 20 ------------- g3doc/how_to_write_documentation.md | 29 +++++++++---------- g3doc/implementation_basics.md | 4 +-- g3doc/index.md | 6 ++-- g3doc/sitemap.md | 5 ++++ g3doc/style-guide.md | 6 ++-- g3doc/style-guide/h-cc-pairs.md | 8 ++--- g3doc/supported-platforms-and-compilers.md | 6 ++-- logging/g3doc/rtc_event_log.md | 6 ++-- modules/audio_coding/g3doc/index.md | 4 +-- modules/audio_coding/neteq/g3doc/index.md | 4 +-- .../audio_device/g3doc/audio_device_module.md | 6 ++-- modules/audio_mixer/g3doc/index.md | 4 +-- .../g3doc/audio_processing_module.md | 6 ++-- modules/pacing/g3doc/index.md | 4 +-- modules/video_coding/g3doc/index.md | 4 +-- native-api.md | 3 ++ p2p/g3doc/ice.md | 6 ++-- pc/g3doc/dtls_transport.md | 4 +-- pc/g3doc/peer_connection.md | 4 +-- pc/g3doc/rtp.md | 4 +-- pc/g3doc/sctp_transport.md | 5 ++-- pc/g3doc/srtp.md | 4 +-- stats/g3doc/stats.md | 4 +-- test/network/g3doc/g3doc.lua | 5 ---- test/network/g3doc/index.md | 5 ++-- test/pc/e2e/g3doc/architecture.md | 3 +- .../g3doc/default_video_quality_analyzer.md | 3 +- test/pc/e2e/g3doc/g3doc.lua | 5 ---- test/pc/e2e/g3doc/index.md | 3 +- video/g3doc/adaptation.md | 4 +-- video/g3doc/stats.md | 4 +-- 40 files changed, 105 insertions(+), 121 deletions(-) delete mode 100644 g3doc.lua delete mode 100644 g3doc/g3doc.lua delete mode 100644 test/network/g3doc/g3doc.lua delete mode 100644 test/pc/e2e/g3doc/g3doc.lua diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index f6b7d0f6a3..14c4886c02 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,3 +1,6 @@ + + + # Contributors Code of Conduct Google and the WebRTC team are committed to preserving and fostering a diverse, welcoming and open diff --git a/api/README.md b/api/README.md index 7c1a27f512..7153cb57c4 100644 --- a/api/README.md +++ b/api/README.md @@ -1,6 +1,9 @@ + + + # How to write code in the `api/` directory -Mostly, just follow the regular [style guide](../g3doc/style-guide.md), but: +Mostly, just follow the regular [style guide](/g3doc/style-guide.md), but: * Note that `api/` code is not exempt from the “`.h` and `.cc` files come in pairs” rule, so if you declare something in `api/path/to/foo.h`, it should be @@ -17,7 +20,7 @@ it from a `.cc` file, so that users of our API headers won’t transitively For headers in `api/` that need to refer to non-public types, forward declarations are often a lesser evil than including non-public header files. The -usual [rules](../g3doc/style-guide.md#forward-declarations) still apply, though. +usual [rules](/g3doc/style-guide.md#forward-declarations) still apply, though. `.cc` files in `api/` should preferably be kept reasonably small. If a substantial implementation is needed, consider putting it with our non-public diff --git a/api/g3doc/index.md b/api/g3doc/index.md index 0c7136c039..b576514d5e 100644 --- a/api/g3doc/index.md +++ b/api/g3doc/index.md @@ -1,5 +1,5 @@ - - + + # The WebRTC API diff --git a/api/g3doc/threading_design.md b/api/g3doc/threading_design.md index 20c3539b22..8023b5eda0 100644 --- a/api/g3doc/threading_design.md +++ b/api/g3doc/threading_design.md @@ -1,5 +1,6 @@ - - + + + # API Threading Design considerations The header files in this directory form the API to the WebRTC library diff --git a/g3doc.lua b/g3doc.lua deleted file mode 100644 index 85d8474a12..0000000000 --- a/g3doc.lua +++ /dev/null @@ -1 +0,0 @@ -return require(this.dirname..'g3doc/g3doc.lua') diff --git a/g3doc/abseil-in-webrtc.md b/g3doc/abseil-in-webrtc.md index 80572a3245..32fc42d953 100644 --- a/g3doc/abseil-in-webrtc.md +++ b/g3doc/abseil-in-webrtc.md @@ -1,7 +1,7 @@ -# Using Abseil in WebRTC + + - - +# Using Abseil in WebRTC You may use a subset of the utilities provided by the [Abseil][abseil] library when writing WebRTC C++ code. Below, we list the explicitly diff --git a/g3doc/become_a_committer.md b/g3doc/become_a_committer.md index 8045c067f3..b2f49721e1 100644 --- a/g3doc/become_a_committer.md +++ b/g3doc/become_a_committer.md @@ -1,7 +1,7 @@ -# How to get tryjob access or become WebRTC committer + + - - +# How to get tryjob access or become WebRTC committer ## Overview diff --git a/g3doc/field-trials.md b/g3doc/field-trials.md index 66246dea9d..e4f946a175 100644 --- a/g3doc/field-trials.md +++ b/g3doc/field-trials.md @@ -1,7 +1,7 @@ -# Field trials + + - - +# Field trials WebRTC provides some means to alter its default behavior during run-time, colloquially known as *field trials*. This is foremost used for A/B testing new diff --git a/g3doc/g3doc.lua b/g3doc/g3doc.lua deleted file mode 100644 index e97289ff81..0000000000 --- a/g3doc/g3doc.lua +++ /dev/null @@ -1,20 +0,0 @@ -return { - theme = { - '@builtins/theme/ng.md', - -- We don't want to have more than h3 headings in the Table Of Content. - toc_level = 3, - }, - - site = { - name = 'WebRTC C++ library', - home = this.dirname..'index.md', - logo = this.dirname..'logo.svg', - map = this.dirname..'sitemap.md', - -- Ensure absolute links are rewritten correctly. - root = this.dirname..'..' - }, - - visibility = { '/...' }, - - freshness = {} -} diff --git a/g3doc/how_to_write_documentation.md b/g3doc/how_to_write_documentation.md index a29d686e66..6c6a4902ee 100644 --- a/g3doc/how_to_write_documentation.md +++ b/g3doc/how_to_write_documentation.md @@ -1,7 +1,7 @@ -# How to write WebRTC documentation + + - - +# How to write WebRTC documentation ## Audience @@ -15,7 +15,7 @@ documentation can skip some edge cases in favor of clarity. The main point is to impart understanding. Conceptual documentation often cannot be embedded directly within the source -code because it usually describes multiple APIs and entites, so the only +code because it usually describes multiple APIs and entities, so the only logical place to document such complex behavior is through a separate conceptual document. @@ -28,7 +28,14 @@ usage and leave rare ones or side effects for class/function level comments. In the WebRTC repo, conceptual documentation is located in `g3doc` subfolders of related components. To add a new document for the component `Foo` find a `g3doc` subfolder for this component and create a `.md` file there with -desired documentation. If there is no `g3doc` subfolder, create a new one; +desired documentation. If there is no `g3doc` subfolder, create a new one. + +Please put the following file header into any created documentation file as the +first line: + +```markdown + +``` When you want to specify a link from one page to another - use the absolute path: @@ -42,17 +49,7 @@ keeping this documentation updated, by adding the next lines at the beginning of your `.md` file immediately after page title: ```markdown -' %?> -' %?> -``` - -If you want to configure the owner for all pages under a directory, create a -`g3doc.lua` file in that directory with the content: - -```lua -config = super() -config.freshness.owner = '' -return config + ``` After the document is ready you should add it into `/g3doc/sitemap.md`, so it diff --git a/g3doc/implementation_basics.md b/g3doc/implementation_basics.md index fce476b94b..ae1f199b68 100644 --- a/g3doc/implementation_basics.md +++ b/g3doc/implementation_basics.md @@ -1,5 +1,5 @@ - - + + # Basic concepts and primitives diff --git a/g3doc/index.md b/g3doc/index.md index 50a3934a4e..8016054d3c 100644 --- a/g3doc/index.md +++ b/g3doc/index.md @@ -1,6 +1,6 @@ + + + # WebRTC C++ library - - - This is a home page for WebRTC C++ library documentation diff --git a/g3doc/sitemap.md b/g3doc/sitemap.md index f3230e1116..664028ca6e 100644 --- a/g3doc/sitemap.md +++ b/g3doc/sitemap.md @@ -2,9 +2,14 @@ * How to contribute * Code * [Style guide](/g3doc/style-guide.md) + * [`.h` and `.cc` files come in pairs](g3doc/style-guide/h-cc-pairs.md) + * [How to write code in the `api/` directory](/api/README.md) + * [Using Abseil in WebRTC](/g3doc/abseil-in-webrtc.md) + * [Code of conduct](/CODE_OF_CONDUCT.md) * [Documentation](/g3doc/how_to_write_documentation.md) * [Become a committer](/g3doc/become_a_committer.md) * [Public C++ API](/api/g3doc/index.md) + * [API header files](/native-api.md) * [Threading](/api/g3doc/threading_design.md) * Implementation * [Basic concepts](/g3doc/implementation_basics.md) diff --git a/g3doc/style-guide.md b/g3doc/style-guide.md index fa0d3e6a78..71d1196df2 100644 --- a/g3doc/style-guide.md +++ b/g3doc/style-guide.md @@ -1,7 +1,7 @@ -# WebRTC coding style guide + + - - +# WebRTC coding style guide ## General advice diff --git a/g3doc/style-guide/h-cc-pairs.md b/g3doc/style-guide/h-cc-pairs.md index bb85871260..08eed85c23 100644 --- a/g3doc/style-guide/h-cc-pairs.md +++ b/g3doc/style-guide/h-cc-pairs.md @@ -1,9 +1,9 @@ + + + # `.h` and `.cc` files come in pairs - - - -This is an overflow page for [this](../style-guide.md#h-cc-pairs) +This is an overflow page for [this](/g3doc/style-guide.md#h-cc-pairs) style rule. ## Example violations diff --git a/g3doc/supported-platforms-and-compilers.md b/g3doc/supported-platforms-and-compilers.md index aa393bbda4..4e65767499 100644 --- a/g3doc/supported-platforms-and-compilers.md +++ b/g3doc/supported-platforms-and-compilers.md @@ -1,7 +1,7 @@ -# WebRTC supported plaftorms and compilers + + - - +# WebRTC supported plaftorms and compilers ## Operating systems and CPUs diff --git a/logging/g3doc/rtc_event_log.md b/logging/g3doc/rtc_event_log.md index 6b81de1066..7ffeb68840 100644 --- a/logging/g3doc/rtc_event_log.md +++ b/logging/g3doc/rtc_event_log.md @@ -1,7 +1,7 @@ -# RTC event log + + - - +# RTC event log ## Overview diff --git a/modules/audio_coding/g3doc/index.md b/modules/audio_coding/g3doc/index.md index d0f6b9f81b..467563e696 100644 --- a/modules/audio_coding/g3doc/index.md +++ b/modules/audio_coding/g3doc/index.md @@ -1,5 +1,5 @@ - - + + # The WebRTC Audio Coding Module diff --git a/modules/audio_coding/neteq/g3doc/index.md b/modules/audio_coding/neteq/g3doc/index.md index e97324d89d..40e76e2742 100644 --- a/modules/audio_coding/neteq/g3doc/index.md +++ b/modules/audio_coding/neteq/g3doc/index.md @@ -1,5 +1,5 @@ - - + + # NetEq diff --git a/modules/audio_device/g3doc/audio_device_module.md b/modules/audio_device/g3doc/audio_device_module.md index 101b2e4cc8..e325faacad 100644 --- a/modules/audio_device/g3doc/audio_device_module.md +++ b/modules/audio_device/g3doc/audio_device_module.md @@ -1,7 +1,7 @@ -# Audio Device Module (ADM) + + - - +# Audio Device Module (ADM) ## Overview diff --git a/modules/audio_mixer/g3doc/index.md b/modules/audio_mixer/g3doc/index.md index 4ced289bf8..6b48378fcb 100644 --- a/modules/audio_mixer/g3doc/index.md +++ b/modules/audio_mixer/g3doc/index.md @@ -1,5 +1,5 @@ - - + + # The WebRTC Audio Mixer Module diff --git a/modules/audio_processing/g3doc/audio_processing_module.md b/modules/audio_processing/g3doc/audio_processing_module.md index fc63b34dfe..a77f62fbaf 100644 --- a/modules/audio_processing/g3doc/audio_processing_module.md +++ b/modules/audio_processing/g3doc/audio_processing_module.md @@ -1,7 +1,7 @@ -# Audio Processing Module (APM) + + - - +# Audio Processing Module (APM) ## Overview diff --git a/modules/pacing/g3doc/index.md b/modules/pacing/g3doc/index.md index edc548a8b4..69f1e69513 100644 --- a/modules/pacing/g3doc/index.md +++ b/modules/pacing/g3doc/index.md @@ -1,5 +1,5 @@ - - + + # Paced Sending diff --git a/modules/video_coding/g3doc/index.md b/modules/video_coding/g3doc/index.md index 2e5695b715..fdf39982fa 100644 --- a/modules/video_coding/g3doc/index.md +++ b/modules/video_coding/g3doc/index.md @@ -1,5 +1,5 @@ - - + + # Video coding in WebRTC diff --git a/native-api.md b/native-api.md index 53e6b1cc93..edd68e2f75 100644 --- a/native-api.md +++ b/native-api.md @@ -1,3 +1,6 @@ + + + # API header files As a user of the WebRTC library, you may use headers and build files diff --git a/p2p/g3doc/ice.md b/p2p/g3doc/ice.md index eef979b0d4..81c9541b64 100644 --- a/p2p/g3doc/ice.md +++ b/p2p/g3doc/ice.md @@ -1,7 +1,7 @@ -# ICE + + - - +# ICE ## Overview diff --git a/pc/g3doc/dtls_transport.md b/pc/g3doc/dtls_transport.md index b5343c16d1..28d6739413 100644 --- a/pc/g3doc/dtls_transport.md +++ b/pc/g3doc/dtls_transport.md @@ -1,5 +1,5 @@ - - + + ## Overview diff --git a/pc/g3doc/peer_connection.md b/pc/g3doc/peer_connection.md index 1eae135991..cd01265cff 100644 --- a/pc/g3doc/peer_connection.md +++ b/pc/g3doc/peer_connection.md @@ -1,5 +1,5 @@ - - + + # PeerConnection and friends diff --git a/pc/g3doc/rtp.md b/pc/g3doc/rtp.md index 38c1702ad3..28da3fba97 100644 --- a/pc/g3doc/rtp.md +++ b/pc/g3doc/rtp.md @@ -1,5 +1,5 @@ - - + + # RTP in WebRTC diff --git a/pc/g3doc/sctp_transport.md b/pc/g3doc/sctp_transport.md index 266387cdf0..161315324e 100644 --- a/pc/g3doc/sctp_transport.md +++ b/pc/g3doc/sctp_transport.md @@ -1,6 +1,5 @@ - - - + + # SctpTransport diff --git a/pc/g3doc/srtp.md b/pc/g3doc/srtp.md index 47446157c9..eb457efacf 100644 --- a/pc/g3doc/srtp.md +++ b/pc/g3doc/srtp.md @@ -1,5 +1,5 @@ - - + + # SRTP in WebRTC diff --git a/stats/g3doc/stats.md b/stats/g3doc/stats.md index 790e101727..25127dc36e 100644 --- a/stats/g3doc/stats.md +++ b/stats/g3doc/stats.md @@ -1,5 +1,5 @@ - - + + # getStats in WebRTC diff --git a/test/network/g3doc/g3doc.lua b/test/network/g3doc/g3doc.lua deleted file mode 100644 index 981393c826..0000000000 --- a/test/network/g3doc/g3doc.lua +++ /dev/null @@ -1,5 +0,0 @@ -config = super() - -config.freshness.owner = 'titovartem' - -return config diff --git a/test/network/g3doc/index.md b/test/network/g3doc/index.md index 5d511916c1..c82b56445e 100644 --- a/test/network/g3doc/index.md +++ b/test/network/g3doc/index.md @@ -1,6 +1,7 @@ -# Network Emulation Framework + + - +# Network Emulation Framework [TOC] diff --git a/test/pc/e2e/g3doc/architecture.md b/test/pc/e2e/g3doc/architecture.md index aacdf7e5d5..1b68c6db2c 100644 --- a/test/pc/e2e/g3doc/architecture.md +++ b/test/pc/e2e/g3doc/architecture.md @@ -1,4 +1,5 @@ - + + # PeerConnection level framework fixture architecture diff --git a/test/pc/e2e/g3doc/default_video_quality_analyzer.md b/test/pc/e2e/g3doc/default_video_quality_analyzer.md index ed182d833d..67596777f2 100644 --- a/test/pc/e2e/g3doc/default_video_quality_analyzer.md +++ b/test/pc/e2e/g3doc/default_video_quality_analyzer.md @@ -1,4 +1,5 @@ - + + # DefaultVideoQualityAnalyzer diff --git a/test/pc/e2e/g3doc/g3doc.lua b/test/pc/e2e/g3doc/g3doc.lua deleted file mode 100644 index 981393c826..0000000000 --- a/test/pc/e2e/g3doc/g3doc.lua +++ /dev/null @@ -1,5 +0,0 @@ -config = super() - -config.freshness.owner = 'titovartem' - -return config diff --git a/test/pc/e2e/g3doc/index.md b/test/pc/e2e/g3doc/index.md index 5a3c9a7e41..678262bb2b 100644 --- a/test/pc/e2e/g3doc/index.md +++ b/test/pc/e2e/g3doc/index.md @@ -1,4 +1,5 @@ - + + # PeerConnection Level Framework diff --git a/video/g3doc/adaptation.md b/video/g3doc/adaptation.md index 463f82caef..cb06e886b2 100644 --- a/video/g3doc/adaptation.md +++ b/video/g3doc/adaptation.md @@ -1,5 +1,5 @@ - - + + # Video Adaptation diff --git a/video/g3doc/stats.md b/video/g3doc/stats.md index 0a423e12ff..7d485a0155 100644 --- a/video/g3doc/stats.md +++ b/video/g3doc/stats.md @@ -1,5 +1,5 @@ - - + + # Video stats