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}
diff --git a/g3doc.lua b/g3doc.lua
new file mode 100644
index 0000000..85d8474
--- /dev/null
+++ b/g3doc.lua
@@ -0,0 +1 @@
+return require(this.dirname..'g3doc/g3doc.lua')
diff --git a/g3doc/g3doc.lua b/g3doc/g3doc.lua
index c6ab162..e97289f 100644
--- a/g3doc/g3doc.lua
+++ b/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',
- logo = '/g3doc/logo.svg',
- map = '/g3doc/sitemap.md',
+ 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 = { '/...' },
diff --git a/g3doc/how_to_write_documentation.md b/g3doc/how_to_write_documentation.md
index aa0414c..6fbca11 100644
--- a/g3doc/how_to_write_documentation.md
+++ b/g3doc/how_to_write_documentation.md
@@ -28,35 +28,44 @@
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
-and add `g3doc.lua` file there with following content:
+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:
```
-config = require('/g3doc/g3doc.lua')
-return config
+[My document](/module/g3doc/my_document.md)
```
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
-markdown. This is processed by multiple tools, so we recommend using only simple
-markup, and previewing the documents in multiple viewers if possible.
+The documentation is written in GitHub Markdown
+([spec](https://github.github.com/gfm/#:~:text=GitHub%20Flavored%20Markdown%2C%20often%20shortened,a%20strict%20superset%20of%20CommonMark.)).
## 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.
diff --git a/test/network/g3doc/g3doc.lua b/test/network/g3doc/g3doc.lua
index af07b58..981393c 100644
--- a/test/network/g3doc/g3doc.lua
+++ b/test/network/g3doc/g3doc.lua
@@ -1,4 +1,4 @@
-config = require('/g3doc/g3doc.lua')
+config = super()
config.freshness.owner = 'titovartem'
diff --git a/test/pc/e2e/g3doc/g3doc.lua b/test/pc/e2e/g3doc/g3doc.lua
index af07b58..981393c 100644
--- a/test/pc/e2e/g3doc/g3doc.lua
+++ b/test/pc/e2e/g3doc/g3doc.lua
@@ -1,4 +1,4 @@
-config = require('/g3doc/g3doc.lua')
+config = super()
config.freshness.owner = 'titovartem'
