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 <hta@webrtc.org>
Commit-Queue: Artem Titov <titovartem@webrtc.org>
Cr-Commit-Position: refs/heads/main@{#39205}
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index f6b7d0f..14c4886 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -1,3 +1,6 @@
+<!-- go/cmark -->
+<!--* freshness: {owner: 'hta' reviewed: '2021-01-01'} *-->
+
# 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 7c1a27f..7153cb5 100644
--- a/api/README.md
+++ b/api/README.md
@@ -1,6 +1,9 @@
+<!-- go/cmark -->
+<!--* freshness: {owner: 'hta' reviewed: '2021-01-01'} *-->
+
# 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 @@
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 0c7136c..b576514 100644
--- a/api/g3doc/index.md
+++ b/api/g3doc/index.md
@@ -1,5 +1,5 @@
-<?% config.freshness.owner = 'hta' %?>
-<?% config.freshness.reviewed = '2021-04-12' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'hta' reviewed: '2021-04-12'} *-->
# The WebRTC API
diff --git a/api/g3doc/threading_design.md b/api/g3doc/threading_design.md
index 20c3539..8023b5e 100644
--- a/api/g3doc/threading_design.md
+++ b/api/g3doc/threading_design.md
@@ -1,5 +1,6 @@
-<?% config.freshness.owner = 'hta' %?>
-<?% config.freshness.reviewed = '2021-04-12' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'hta' reviewed: '2021-04-12'} *-->
+
# 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 85d8474..0000000
--- 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 80572a3..32fc42d 100644
--- a/g3doc/abseil-in-webrtc.md
+++ b/g3doc/abseil-in-webrtc.md
@@ -1,7 +1,7 @@
-# Using Abseil in WebRTC
+<!-- go/cmark -->
+<!--* freshness: {owner: 'danilchap' reviewed: '2021-05-12'} *-->
-<?% config.freshness.owner = 'danilchap' %?>
-<?% config.freshness.reviewed = '2021-05-12' %?>
+# 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 8045c06..b2f4972 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
+<!-- go/cmark -->
+<!--* freshness: {owner: 'titovartem' reviewed: '2021-10-26'} *-->
-<?% config.freshness.owner = 'titovartem' %?>
-<?% config.freshness.reviewed = '2021-10-26' %?>
+# How to get tryjob access or become WebRTC committer
## Overview
diff --git a/g3doc/field-trials.md b/g3doc/field-trials.md
index 66246de..e4f946a 100644
--- a/g3doc/field-trials.md
+++ b/g3doc/field-trials.md
@@ -1,7 +1,7 @@
-# Field trials
+<!-- go/cmark -->
+<!--* freshness: {owner: 'lndmrk' reviewed: '2022-06-23'} *-->
-<?% config.freshness.owner = 'lndmrk' %?>
-<?% config.freshness.reviewed = '2022-06-23' %?>
+# 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 e97289f..0000000
--- 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 a29d686..6c6a490 100644
--- a/g3doc/how_to_write_documentation.md
+++ b/g3doc/how_to_write_documentation.md
@@ -1,7 +1,7 @@
-# How to write WebRTC documentation
+<!-- go/cmark -->
+<!--* freshness: {owner: 'titovartem' reviewed: '2023-01-16'} *-->
-<?% config.freshness.owner = 'titovartem' %?>
-<?% config.freshness.reviewed = '2021-03-01' %?>
+# How to write WebRTC documentation
## Audience
@@ -15,7 +15,7 @@
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 @@
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
+<!-- go/cmark -->
+```
When you want to specify a link from one page to another - use the absolute
path:
@@ -42,17 +49,7 @@
of your `.md` file immediately after page title:
```markdown
-<?\% config.freshness.owner = '<user name>' %?>
-<?\% config.freshness.reviewed = '<last review date in format yyyy-mm-dd>' %?>
-```
-
-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 = '<user name>'
-return config
+<!--* freshness: {owner: '<user name>' reviewed: '<last review date in format yyyy-mm-dd>' *-->
```
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 fce476b..ae1f199 100644
--- a/g3doc/implementation_basics.md
+++ b/g3doc/implementation_basics.md
@@ -1,5 +1,5 @@
-<?% config.freshness.owner = 'hta' %?>
-<?% config.freshness.reviewed = '2021-05-31' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'hta' reviewed: '2021-05-31'} *-->
# Basic concepts and primitives
diff --git a/g3doc/index.md b/g3doc/index.md
index 50a3934..8016054 100644
--- a/g3doc/index.md
+++ b/g3doc/index.md
@@ -1,6 +1,6 @@
-# WebRTC C++ library
+<!-- go/cmark -->
+<!--* freshness: {owner: 'titovartem' reviewed: '2021-03-01'} *-->
-<?% config.freshness.owner = 'titovartem' %?>
-<?% config.freshness.reviewed = '2021-03-01' %?>
+# WebRTC C++ library
This is a home page for WebRTC C++ library documentation
diff --git a/g3doc/sitemap.md b/g3doc/sitemap.md
index f3230e1..664028c 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 fa0d3e6..71d1196 100644
--- a/g3doc/style-guide.md
+++ b/g3doc/style-guide.md
@@ -1,7 +1,7 @@
-# WebRTC coding style guide
+<!-- go/cmark -->
+<!--* freshness: {owner: 'danilchap' reviewed: '2022-01-17'} *-->
-<?% config.freshness.owner = 'danilchap' %?>
-<?% config.freshness.reviewed = '2022-01-17' %?>
+# 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 bb85871..08eed85 100644
--- a/g3doc/style-guide/h-cc-pairs.md
+++ b/g3doc/style-guide/h-cc-pairs.md
@@ -1,9 +1,9 @@
+<!-- go/cmark -->
+<!--* freshness: {owner: 'danilchap' reviewed: '2021-05-12'} *-->
+
# `.h` and `.cc` files come in pairs
-<?% config.freshness.owner = 'danilchap' %?>
-<?% config.freshness.reviewed = '2021-05-12' %?>
-
-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 aa393bb..4e65767 100644
--- a/g3doc/supported-platforms-and-compilers.md
+++ b/g3doc/supported-platforms-and-compilers.md
@@ -1,7 +1,7 @@
-# WebRTC supported plaftorms and compilers
+<!-- go/cmark -->
+<!--* freshness: {owner: 'mbonadei' reviewed: '2021-06-25'} *-->
-<?% config.freshness.owner = 'mbonadei' %?>
-<?% config.freshness.reviewed = '2021-06-25' %?>
+# 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 6b81de1..7ffeb68 100644
--- a/logging/g3doc/rtc_event_log.md
+++ b/logging/g3doc/rtc_event_log.md
@@ -1,7 +1,7 @@
-# RTC event log
+<!-- go/cmark -->
+<!--* freshness: {owner: 'terelius' reviewed: '2021-06-02'} *-->
-<?% config.freshness.owner = 'terelius' %?>
-<?% config.freshness.reviewed = '2021-06-02' %?>
+# RTC event log
## Overview
diff --git a/modules/audio_coding/g3doc/index.md b/modules/audio_coding/g3doc/index.md
index d0f6b9f..467563e 100644
--- a/modules/audio_coding/g3doc/index.md
+++ b/modules/audio_coding/g3doc/index.md
@@ -1,5 +1,5 @@
-<?% config.freshness.owner = 'minyue' %?>
-<?% config.freshness.reviewed = '2021-04-13' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'hlundin' reviewed: '2021-04-13'} *-->
# The WebRTC Audio Coding Module
diff --git a/modules/audio_coding/neteq/g3doc/index.md b/modules/audio_coding/neteq/g3doc/index.md
index e97324d..40e76e2 100644
--- a/modules/audio_coding/neteq/g3doc/index.md
+++ b/modules/audio_coding/neteq/g3doc/index.md
@@ -1,5 +1,5 @@
-<?% config.freshness.reviewed = '2021-04-13' %?>
-<?% config.freshness.owner = 'jakobi' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'jakobi' reviewed: '2021-04-13'} *-->
# NetEq
diff --git a/modules/audio_device/g3doc/audio_device_module.md b/modules/audio_device/g3doc/audio_device_module.md
index 101b2e4..e325faa 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)
+<!-- go/cmark -->
+<!--* freshness: {owner: 'henrika' reviewed: '2021-04-12'} *-->
-<?% config.freshness.owner = 'henrika' %?>
-<?% config.freshness.reviewed = '2021-04-12' %?>
+# Audio Device Module (ADM)
## Overview
diff --git a/modules/audio_mixer/g3doc/index.md b/modules/audio_mixer/g3doc/index.md
index 4ced289..6b48378 100644
--- a/modules/audio_mixer/g3doc/index.md
+++ b/modules/audio_mixer/g3doc/index.md
@@ -1,5 +1,5 @@
-<?% config.freshness.owner = 'alessiob' %?>
-<?% config.freshness.reviewed = '2021-04-21' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'alessiob' reviewed: '2021-04-21'} *-->
# 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 fc63b34..a77f62f 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)
+<!-- go/cmark -->
+<!--* freshness: {owner: 'peah' reviewed: '2021-04-13'} *-->
-<?% config.freshness.owner = 'peah' %?>
-<?% config.freshness.reviewed = '2021-04-13' %?>
+# Audio Processing Module (APM)
## Overview
diff --git a/modules/pacing/g3doc/index.md b/modules/pacing/g3doc/index.md
index edc548a..69f1e69 100644
--- a/modules/pacing/g3doc/index.md
+++ b/modules/pacing/g3doc/index.md
@@ -1,5 +1,5 @@
-<?% config.freshness.reviewed = '2021-04-12' %?>
-<?% config.freshness.owner = 'sprang' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'sprang' reviewed: '2021-04-12'} *-->
# Paced Sending
diff --git a/modules/video_coding/g3doc/index.md b/modules/video_coding/g3doc/index.md
index 2e5695b..fdf3998 100644
--- a/modules/video_coding/g3doc/index.md
+++ b/modules/video_coding/g3doc/index.md
@@ -1,5 +1,5 @@
-<?% config.freshness.owner = 'brandtr' %?>
-<?% config.freshness.reviewed = '2021-04-15' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'brandtr' reviewed: '2021-04-15'} *-->
# Video coding in WebRTC
diff --git a/native-api.md b/native-api.md
index 53e6b1c..edd68e2 100644
--- a/native-api.md
+++ b/native-api.md
@@ -1,3 +1,6 @@
+<!-- go/cmark -->
+<!--* freshness: {owner: 'hta' reviewed: '2021-01-01'} *-->
+
# 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 eef979b..81c9541 100644
--- a/p2p/g3doc/ice.md
+++ b/p2p/g3doc/ice.md
@@ -1,7 +1,7 @@
-# ICE
+<!-- go/cmark -->
+<!--* freshness: {owner: 'jonaso' reviewed: '2021-04-12'} *-->
-<?% config.freshness.owner = 'jonaso' %?>
-<?% config.freshness.reviewed = '2021-04-12' %?>
+# ICE
## Overview
diff --git a/pc/g3doc/dtls_transport.md b/pc/g3doc/dtls_transport.md
index b5343c1..28d6739 100644
--- a/pc/g3doc/dtls_transport.md
+++ b/pc/g3doc/dtls_transport.md
@@ -1,5 +1,5 @@
-<?% config.freshness.reviewed = '2021-05-07' %?>
-<?% config.freshness.owner = 'hta' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'hta' reviewed: '2021-05-07'} *-->
## Overview
diff --git a/pc/g3doc/peer_connection.md b/pc/g3doc/peer_connection.md
index 1eae135..cd01265 100644
--- a/pc/g3doc/peer_connection.md
+++ b/pc/g3doc/peer_connection.md
@@ -1,5 +1,5 @@
-<?% config.freshness.reviewed = '2021-05-07' %?>
-<?% config.freshness.owner = 'hta' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'hta' reviewed: '2021-05-07'} *-->
# PeerConnection and friends
diff --git a/pc/g3doc/rtp.md b/pc/g3doc/rtp.md
index 38c1702..28da3fb 100644
--- a/pc/g3doc/rtp.md
+++ b/pc/g3doc/rtp.md
@@ -1,5 +1,5 @@
-<?% config.freshness.reviewed = '2021-06-03' %?>
-<?% config.freshness.owner = 'hta' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'hta' reviewed: '2021-06-03'} *-->
# RTP in WebRTC
diff --git a/pc/g3doc/sctp_transport.md b/pc/g3doc/sctp_transport.md
index 266387c..1613153 100644
--- a/pc/g3doc/sctp_transport.md
+++ b/pc/g3doc/sctp_transport.md
@@ -1,6 +1,5 @@
-
-<?% config.freshness.reviewed = '2021-04-13' %?>
-<?% config.freshness.owner = 'hta' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'hta' reviewed: '2021-04-13'} *-->
# SctpTransport
diff --git a/pc/g3doc/srtp.md b/pc/g3doc/srtp.md
index 4744615..eb457ef 100644
--- a/pc/g3doc/srtp.md
+++ b/pc/g3doc/srtp.md
@@ -1,5 +1,5 @@
-<?% config.freshness.reviewed = '2021-05-13' %?>
-<?% config.freshness.owner = 'hta' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'hta' reviewed: '2021-05-13'} *-->
# SRTP in WebRTC
diff --git a/stats/g3doc/stats.md b/stats/g3doc/stats.md
index 790e101..25127dc 100644
--- a/stats/g3doc/stats.md
+++ b/stats/g3doc/stats.md
@@ -1,5 +1,5 @@
-<?% config.freshness.reviewed = '2022-10-01' %?>
-<?% config.freshness.owner = 'hta' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'hta' reviewed: '2022-10-01'} *-->
# getStats in WebRTC
diff --git a/test/network/g3doc/g3doc.lua b/test/network/g3doc/g3doc.lua
deleted file mode 100644
index 981393c..0000000
--- 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 5d51191..c82b564 100644
--- a/test/network/g3doc/index.md
+++ b/test/network/g3doc/index.md
@@ -1,6 +1,7 @@
-# Network Emulation Framework
+<!-- go/cmark -->
+<!--* freshness: {owner: 'titovartem' reviewed: '2021-03-01'} *-->
-<?% config.freshness.reviewed = '2021-03-01' %?>
+# Network Emulation Framework
[TOC]
diff --git a/test/pc/e2e/g3doc/architecture.md b/test/pc/e2e/g3doc/architecture.md
index aacdf7e..1b68c6d 100644
--- a/test/pc/e2e/g3doc/architecture.md
+++ b/test/pc/e2e/g3doc/architecture.md
@@ -1,4 +1,5 @@
-<?% config.freshness.reviewed = '2021-04-12' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'titovartem' reviewed: '2021-04-12'} *-->
# 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 ed182d8..6759677 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 @@
-<?% config.freshness.reviewed = '2021-02-21' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'titovartem' reviewed: '2021-02-21'} *-->
# DefaultVideoQualityAnalyzer
diff --git a/test/pc/e2e/g3doc/g3doc.lua b/test/pc/e2e/g3doc/g3doc.lua
deleted file mode 100644
index 981393c..0000000
--- 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 5a3c9a7..678262b 100644
--- a/test/pc/e2e/g3doc/index.md
+++ b/test/pc/e2e/g3doc/index.md
@@ -1,4 +1,5 @@
-<?% config.freshness.reviewed = '2021-04-12' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'titovartem' reviewed: '2021-04-12'} *-->
# PeerConnection Level Framework
diff --git a/video/g3doc/adaptation.md b/video/g3doc/adaptation.md
index 463f82c..cb06e88 100644
--- a/video/g3doc/adaptation.md
+++ b/video/g3doc/adaptation.md
@@ -1,5 +1,5 @@
-<?% config.freshness.reviewed = '2021-04-13' %?>
-<?% config.freshness.owner = 'eshr' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'eshr' reviewed: '2021-04-13'} *-->
# Video Adaptation
diff --git a/video/g3doc/stats.md b/video/g3doc/stats.md
index 0a423e1..7d485a0 100644
--- a/video/g3doc/stats.md
+++ b/video/g3doc/stats.md
@@ -1,5 +1,5 @@
-<?% config.freshness.reviewed = '2021-04-14' %?>
-<?% config.freshness.owner = 'asapersson' %?>
+<!-- go/cmark -->
+<!--* freshness: {owner: 'asapersson' reviewed: '2021-04-14'} *-->
# Video stats
