Improve webrtc documentation infra. Preview at:

https://g3doc-ng.corp.google.com/gob/webrtc/src/+/refs/changes/213189/1/g3doc/how_to_write_documentation.md

Bug: webrtc:12545
Change-Id: I284714f9e4e39f10eda03cc464ca695e8b272cd7
Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/213189
Reviewed-by: Artem Titov <titovartem@webrtc.org>
Reviewed-by: Tommi <tommi@webrtc.org>
Commit-Queue: Artem Titov <titovartem@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#33593}

g3doc.lua

@@ -0,0 +1 @@
+return require(this.dirname..'g3doc/g3doc.lua')

g3doc/g3doc.lua

@@ -1,15 +1,17 @@
 return {
   theme = {
-    '@builtins/theme/ng.md'
+    '@builtins/theme/ng.md',
     -- We don't want to have more than h3 headings in the Table Of Content.
-    --toc_level = 3,
+    toc_level = 3,
   },
 
   site = {
     name = 'WebRTC C++ library',
-    home = '/g3doc/index.md',
+    home = this.dirname..'index.md',
-    logo = '/g3doc/logo.svg',
+    logo = this.dirname..'logo.svg',
-    map  = '/g3doc/sitemap.md',
+    map  = this.dirname..'sitemap.md',
+    -- Ensure absolute links are rewritten correctly.
+    root = this.dirname..'..'
   },
 
   visibility = { '/...' },

g3doc/how_to_write_documentation.md

@@ -28,35 +28,44 @@ 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;
-and add `g3doc.lua` file there with following content:
+
+When you want to specify a link from one page to another - use the absolute
+path:
 
 ```
-config = require('/g3doc/g3doc.lua')
+[My document](/module/g3doc/my_document.md)
-return config
 ```
 
 If you are a Googler also please specify an owner, who will be responsible for
 keeping this documentation updated, by adding the next lines at the beginning
 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
+```
+
 After the document is ready you should add it into `/g3doc/sitemap.md`, so it
-will be visible for others.
+will be discoverable by others.
 
 ### Documentation format
 
-The documentation is written in g3doc, which is a markup format derived from
+The documentation is written in GitHub Markdown
-markdown. This is processed by multiple tools, so we recommend using only simple
+([spec](https://github.github.com/gfm/#:~:text=GitHub%20Flavored%20Markdown%2C%20often%20shortened,a%20strict%20superset%20of%20CommonMark.)).
-markup, and previewing the documents in multiple viewers if possible.
 
 ## Class/function level comments
 
-Documentation of specific classes and function APIs and their usage, inculding
+Documentation of specific classes and function APIs and their usage, including
 their purpose, is embedded in the .h files defining that API. See
 [C++ style guide](https://chromium.googlesource.com/chromium/src/+/master/styleguide/c++/c++.md)
 for pointers on how to write API documentatin in .h files.

test/network/g3doc/g3doc.lua

@@ -1,4 +1,4 @@
-config = require('/g3doc/g3doc.lua')
+config = super()
 
 config.freshness.owner = 'titovartem'
 

test/pc/e2e/g3doc/g3doc.lua

@@ -1,4 +1,4 @@
-config = require('/g3doc/g3doc.lua')
+config = super()
 
 config.freshness.owner = 'titovartem'