From 0f2ce5cc1c779f9bf33f51f29bfffbcbe105d1b1 Mon Sep 17 00:00:00 2001 From: Artem Titov Date: Thu, 26 Jan 2023 20:18:46 +0000 Subject: [PATCH] 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} --- 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, 121 insertions(+), 105 deletions(-) create mode 100644 g3doc.lua create mode 100644 g3doc/g3doc.lua create mode 100644 test/network/g3doc/g3doc.lua create mode 100644 test/pc/e2e/g3doc/g3doc.lua diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 14c4886c02..f6b7d0f6a3 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,6 +1,3 @@ - - - # 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 7153cb57c4..7c1a27f512 100644 --- a/api/README.md +++ b/api/README.md @@ -1,9 +1,6 @@ - - - # 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 @@ -20,7 +17,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 b576514d5e..0c7136c039 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 8023b5eda0..20c3539b22 100644 --- a/api/g3doc/threading_design.md +++ b/api/g3doc/threading_design.md @@ -1,6 +1,5 @@ - - - + + # 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 new file mode 100644 index 0000000000..85d8474a12 --- /dev/null +++ b/g3doc.lua @@ -0,0 +1 @@ +return require(this.dirname..'g3doc/g3doc.lua') diff --git a/g3doc/abseil-in-webrtc.md b/g3doc/abseil-in-webrtc.md index 32fc42d953..80572a3245 100644 --- a/g3doc/abseil-in-webrtc.md +++ b/g3doc/abseil-in-webrtc.md @@ -1,8 +1,8 @@ - - - # 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 *allowed* and the explicitly *disallowed* subsets of Abseil; if you diff --git a/g3doc/become_a_committer.md b/g3doc/become_a_committer.md index b2f49721e1..8045c067f3 100644 --- a/g3doc/become_a_committer.md +++ b/g3doc/become_a_committer.md @@ -1,8 +1,8 @@ - - - # How to get tryjob access or become WebRTC committer + + + ## Overview There are two levels of WebRTC contributors access: diff --git a/g3doc/field-trials.md b/g3doc/field-trials.md index e4f946a175..66246dea9d 100644 --- a/g3doc/field-trials.md +++ b/g3doc/field-trials.md @@ -1,8 +1,8 @@ - - - # 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 features and are related to diff --git a/g3doc/g3doc.lua b/g3doc/g3doc.lua new file mode 100644 index 0000000000..e97289ff81 --- /dev/null +++ b/g3doc/g3doc.lua @@ -0,0 +1,20 @@ +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 6c6a4902ee..a29d686e66 100644 --- a/g3doc/how_to_write_documentation.md +++ b/g3doc/how_to_write_documentation.md @@ -1,8 +1,8 @@ - - - # How to write WebRTC documentation + + + ## Audience Engineers and tech writers who wants to contribute to WebRTC documentation @@ -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 entities, so the only +code because it usually describes multiple APIs and entites, so the only logical place to document such complex behavior is through a separate conceptual document. @@ -28,14 +28,7 @@ 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. - -Please put the following file header into any created documentation file as the -first line: - -```markdown - -``` +desired documentation. If there is no `g3doc` subfolder, create a new one; When you want to specify a link from one page to another - use the absolute path: @@ -49,7 +42,17 @@ 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 ae1f199b68..fce476b94b 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 8016054d3c..50a3934a4e 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 664028ca6e..f3230e1116 100644 --- a/g3doc/sitemap.md +++ b/g3doc/sitemap.md @@ -2,14 +2,9 @@ * 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 71d1196df2..fa0d3e6a78 100644 --- a/g3doc/style-guide.md +++ b/g3doc/style-guide.md @@ -1,8 +1,8 @@ - - - # WebRTC coding style guide + + + ## General advice Some older parts of the code violate the style guide in various ways. diff --git a/g3doc/style-guide/h-cc-pairs.md b/g3doc/style-guide/h-cc-pairs.md index 08eed85c23..bb85871260 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](/g3doc/style-guide.md#h-cc-pairs) + + + +This is an overflow page for [this](../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 4e65767499..aa393bbda4 100644 --- a/g3doc/supported-platforms-and-compilers.md +++ b/g3doc/supported-platforms-and-compilers.md @@ -1,8 +1,8 @@ - - - # WebRTC supported plaftorms and compilers + + + ## Operating systems and CPUs The list of officially supported operating systems and CPUs is: diff --git a/logging/g3doc/rtc_event_log.md b/logging/g3doc/rtc_event_log.md index 7ffeb68840..6b81de1066 100644 --- a/logging/g3doc/rtc_event_log.md +++ b/logging/g3doc/rtc_event_log.md @@ -1,8 +1,8 @@ - - - # RTC event log + + + ## Overview RTC event logs can be enabled to capture in-depth inpformation about sent and diff --git a/modules/audio_coding/g3doc/index.md b/modules/audio_coding/g3doc/index.md index 467563e696..d0f6b9f81b 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 40e76e2742..e97324d89d 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 e325faacad..101b2e4cc8 100644 --- a/modules/audio_device/g3doc/audio_device_module.md +++ b/modules/audio_device/g3doc/audio_device_module.md @@ -1,8 +1,8 @@ - - - # Audio Device Module (ADM) + + + ## Overview The ADM is responsible for driving input (microphone) and output (speaker) audio diff --git a/modules/audio_mixer/g3doc/index.md b/modules/audio_mixer/g3doc/index.md index 6b48378fcb..4ced289bf8 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 a77f62fbaf..fc63b34dfe 100644 --- a/modules/audio_processing/g3doc/audio_processing_module.md +++ b/modules/audio_processing/g3doc/audio_processing_module.md @@ -1,8 +1,8 @@ - - - # Audio Processing Module (APM) + + + ## Overview The APM is responsible for applying speech enhancements effects to the diff --git a/modules/pacing/g3doc/index.md b/modules/pacing/g3doc/index.md index 69f1e69513..edc548a8b4 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 fdf39982fa..2e5695b715 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 edd68e2f75..53e6b1cc93 100644 --- a/native-api.md +++ b/native-api.md @@ -1,6 +1,3 @@ - - - # 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 81c9541b64..eef979b0d4 100644 --- a/p2p/g3doc/ice.md +++ b/p2p/g3doc/ice.md @@ -1,8 +1,8 @@ - - - # ICE + + + ## Overview ICE ([link](https://developer.mozilla.org/en-US/docs/Glossary/ICE)) provides diff --git a/pc/g3doc/dtls_transport.md b/pc/g3doc/dtls_transport.md index 28d6739413..b5343c16d1 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 cd01265cff..1eae135991 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 28da3fba97..38c1702ad3 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 161315324e..266387cdf0 100644 --- a/pc/g3doc/sctp_transport.md +++ b/pc/g3doc/sctp_transport.md @@ -1,5 +1,6 @@ - - + + + # SctpTransport diff --git a/pc/g3doc/srtp.md b/pc/g3doc/srtp.md index eb457efacf..47446157c9 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 25127dc36e..790e101727 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 new file mode 100644 index 0000000000..981393c826 --- /dev/null +++ b/test/network/g3doc/g3doc.lua @@ -0,0 +1,5 @@ +config = super() + +config.freshness.owner = 'titovartem' + +return config diff --git a/test/network/g3doc/index.md b/test/network/g3doc/index.md index c82b56445e..5d511916c1 100644 --- a/test/network/g3doc/index.md +++ b/test/network/g3doc/index.md @@ -1,8 +1,7 @@ - - - # Network Emulation Framework + + [TOC] ## Disclamer diff --git a/test/pc/e2e/g3doc/architecture.md b/test/pc/e2e/g3doc/architecture.md index 1b68c6db2c..aacdf7e5d5 100644 --- a/test/pc/e2e/g3doc/architecture.md +++ b/test/pc/e2e/g3doc/architecture.md @@ -1,5 +1,4 @@ - - + # 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 67596777f2..ed182d833d 100644 --- a/test/pc/e2e/g3doc/default_video_quality_analyzer.md +++ b/test/pc/e2e/g3doc/default_video_quality_analyzer.md @@ -1,5 +1,4 @@ - - + # DefaultVideoQualityAnalyzer diff --git a/test/pc/e2e/g3doc/g3doc.lua b/test/pc/e2e/g3doc/g3doc.lua new file mode 100644 index 0000000000..981393c826 --- /dev/null +++ b/test/pc/e2e/g3doc/g3doc.lua @@ -0,0 +1,5 @@ +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 678262bb2b..5a3c9a7e41 100644 --- a/test/pc/e2e/g3doc/index.md +++ b/test/pc/e2e/g3doc/index.md @@ -1,5 +1,4 @@ - - + # PeerConnection Level Framework diff --git a/video/g3doc/adaptation.md b/video/g3doc/adaptation.md index cb06e886b2..463f82caef 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 7d485a0155..0a423e12ff 100644 --- a/video/g3doc/stats.md +++ b/video/g3doc/stats.md @@ -1,5 +1,5 @@ - - + + # Video stats